From c9fe510ebbe14266519b8feb1e5b687075372dad Mon Sep 17 00:00:00 2001 From: Alexander Kochetov Date: Fri, 10 May 2013 09:52:21 +0400 Subject: [PATCH] Comment fixes + class descriptions added --- framework/rbac/Assignment.php | 9 +++++++++ framework/rbac/DbManager.php | 12 ++++++++++-- framework/rbac/IManager.php | 2 ++ framework/rbac/Item.php | 14 ++++++++++++++ framework/rbac/Manager.php | 24 ++++++++++++++++++++++++ framework/rbac/PhpManager.php | 13 ++++++++++++- 6 files changed, 71 insertions(+), 3 deletions(-) diff --git a/framework/rbac/Assignment.php b/framework/rbac/Assignment.php index 576017e..e5d6157 100644 --- a/framework/rbac/Assignment.php +++ b/framework/rbac/Assignment.php @@ -11,6 +11,15 @@ use Yii; use yii\base\Object; /** + * Assignment represents an assignment of a role to a user. + * It includes additional assignment information such as [[bizRule]] and [[data]]. + * Do not create a Assignment instance using the 'new' operator. + * Instead, call [[IManager::assign]]. + * + * @property mixed $userId User ID (see [[User::id]]). + * @property string $itemName The authorization item name. + * @property string $bizRule The business rule associated with this assignment. + * @property mixed $data Additional data for this assignment. * * @author Qiang Xue * @author Alexander Kochetov diff --git a/framework/rbac/DbManager.php b/framework/rbac/DbManager.php index 5f64694..d3c584c 100644 --- a/framework/rbac/DbManager.php +++ b/framework/rbac/DbManager.php @@ -14,6 +14,14 @@ use yii\base\Exception; use yii\base\InvalidConfigException; /** + * DbManager represents an authorization manager that stores authorization information in database. + * + * The database connection is specified by [[db]]. And the database schema + * should be as described in "framework/rbac/*.sql". You may change the names of + * the three tables used to store the authorization data by setting [[itemTable]], + * [[itemChildTable]] and [[assignmentTable]]. + * + * @property array $authItems The authorization items of the specific type. * * @author Qiang Xue * @author Alexander Kochetov @@ -60,9 +68,9 @@ class DbManager extends Manager /** * Performs access check for the specified user. - * @param mixed $userId the user ID. This should can be either an integer and a string representing - * @param string $itemName the name of the operation that need access check + * @param mixed $userId the user ID. This should can be either an integer or a string representing * the unique identifier of a user. See [[User::id]]. + * @param string $itemName the name of the operation that need access check * @param array $params name-value pairs that would be passed to biz rules associated * with the tasks and roles assigned to the user. A param with name 'userId' is added to this array, * which holds the value of `$userId`. diff --git a/framework/rbac/IManager.php b/framework/rbac/IManager.php index 6eeb661..0e9eea0 100644 --- a/framework/rbac/IManager.php +++ b/framework/rbac/IManager.php @@ -10,6 +10,8 @@ namespace yii\rbac; /** * IManager interface is implemented by an auth manager application component. * + * An auth manager is mainly responsible for providing role-based access control (RBAC) service. + * * @author Qiang Xue * @author Alexander Kochetov * @since 2.0 diff --git a/framework/rbac/Item.php b/framework/rbac/Item.php index d09196f..1297e41 100644 --- a/framework/rbac/Item.php +++ b/framework/rbac/Item.php @@ -11,6 +11,20 @@ use Yii; use yii\base\Object; /** + * Item represents an authorization item. + * An authorization item can be an operation, a task or a role. + * They form an authorization hierarchy. Items on higher levels of the hierarchy + * inherit the permissions represented by items on lower levels. + * A user may be assigned one or several authorization items (called [[Assignment]] assignments). + * He can perform an operation only when it is among his assigned items. + * + * @property IManager $authManager The authorization manager. + * @property integer $type The authorization item type. This could be 0 (operation), 1 (task) or 2 (role). + * @property string $name The item name. + * @property string $description The item description. + * @property string $bizRule The business rule associated with this item. + * @property mixed $data The additional data associated with this item. + * @property array $children All child items of this item. * * @author Qiang Xue * @author Alexander Kochetov diff --git a/framework/rbac/Manager.php b/framework/rbac/Manager.php index 4846546..6d0b74d 100644 --- a/framework/rbac/Manager.php +++ b/framework/rbac/Manager.php @@ -12,6 +12,30 @@ use yii\base\Component; use yii\base\Exception; /** + * Manager is the base class for authorization manager classes. + * + * Manager extends [[Component]] and implements some methods + * that are common among authorization manager classes. + * + * Manager together with its concrete child classes implement the Role-Based + * Access Control (RBAC). + * + * The main idea is that permissions are organized as a hierarchy of + * [[Item]] authorization items. Items on higer level inherit the permissions + * represented by items on lower level. And roles are simply top-level authorization items + * that may be assigned to individual users. A user is said to have a permission + * to do something if the corresponding authorization item is inherited by one of his roles. + * + * Using authorization manager consists of two aspects. First, the authorization hierarchy + * and assignments have to be established. Manager and its child classes + * provides APIs to accomplish this task. Developers may need to develop some GUI + * so that it is more intuitive to end-users. Second, developers call [[IManager::checkAccess()]] + * at appropriate places in the application code to check if the current user + * has the needed permission for an operation. + * + * @property array $roles Roles (name=>Item). + * @property array $tasks Tasks (name=>Item). + * @property array $operations Operations (name=>Item). * * @author Qiang Xue * @author Alexander Kochetov diff --git a/framework/rbac/PhpManager.php b/framework/rbac/PhpManager.php index 3f471c6..baacb36 100644 --- a/framework/rbac/PhpManager.php +++ b/framework/rbac/PhpManager.php @@ -11,6 +11,17 @@ use Yii; use yii\base\Exception; /** + * PhpManager represents an authorization manager that stores authorization + * information in terms of a PHP script file. + * + * The authorization data will be saved to and loaded from a file + * specified by [[authFile]], which defaults to 'protected/data/rbac.php'. + * + * PhpManager is mainly suitable for authorization data that is not too big + * (for example, the authorization data for a personal blog system). + * Use [[DbManager]] for more complex authorization data. + * + * @property array $authItems The authorization items of the specific type. * * @author Qiang Xue * @author Alexander Kochetov @@ -20,7 +31,7 @@ class PhpManager extends Manager { /** * @var string the path of the PHP script that contains the authorization data. - * If not set, it will be using 'protected/data/auth.php' as the data file. + * If not set, it will be using 'protected/data/rbac.php' as the data file. * Make sure this file is writable by the Web server process if the authorization * needs to be changed. * @see loadFromFile