1: <?php
2: /**
3: * CAuthManager class file.
4: *
5: * @author Qiang Xue <qiang.xue@gmail.com>
6: * @link http://www.yiiframework.com/
7: * @copyright 2008-2013 Yii Software LLC
8: * @license http://www.yiiframework.com/license/
9: */
10:
11: /**
12: * CAuthManager is the base class for authorization manager classes.
13: *
14: * CAuthManager extends {@link CApplicationComponent} and implements some methods
15: * that are common among authorization manager classes.
16: *
17: * CAuthManager together with its concrete child classes implement the Role-Based
18: * Access Control (RBAC).
19: *
20: * The main idea is that permissions are organized as a hierarchy of
21: * {@link CAuthItem authorization items}. Items on higher level inherit the permissions
22: * represented by items on lower level. And roles are simply top-level authorization items
23: * that may be assigned to individual users. A user is said to have a permission
24: * to do something if the corresponding authorization item is inherited by one of his roles.
25: *
26: * Using authorization manager consists of two aspects. First, the authorization hierarchy
27: * and assignments have to be established. CAuthManager and its child classes
28: * provides APIs to accomplish this task. Developers may need to develop some GUI
29: * so that it is more intuitive to end-users. Second, developers call {@link IAuthManager::checkAccess}
30: * at appropriate places in the application code to check if the current user
31: * has the needed permission for an operation.
32: *
33: * @property array $roles Roles (name=>CAuthItem).
34: * @property array $tasks Tasks (name=>CAuthItem).
35: * @property array $operations Operations (name=>CAuthItem).
36: *
37: * @author Qiang Xue <qiang.xue@gmail.com>
38: * @package system.web.auth
39: * @since 1.0
40: */
41: abstract class CAuthManager extends CApplicationComponent implements IAuthManager
42: {
43: /**
44: * @var boolean Enable error reporting for bizRules.
45: * @since 1.1.3
46: */
47: public $showErrors = false;
48:
49: /**
50: * @var array list of role names that are assigned to all users implicitly.
51: * These roles do not need to be explicitly assigned to any user.
52: * When calling {@link checkAccess}, these roles will be checked first.
53: * For performance reason, you should minimize the number of such roles.
54: * A typical usage of such roles is to define an 'authenticated' role and associate
55: * it with a biz rule which checks if the current user is authenticated.
56: * And then declare 'authenticated' in this property so that it can be applied to
57: * every authenticated user.
58: */
59: public $defaultRoles=array();
60:
61: /**
62: * Creates a role.
63: * This is a shortcut method to {@link IAuthManager::createAuthItem}.
64: * @param string $name the item name
65: * @param string $description the item description.
66: * @param string $bizRule the business rule associated with this item
67: * @param mixed $data additional data to be passed when evaluating the business rule
68: * @return CAuthItem the authorization item
69: */
70: public function createRole($name,$description='',$bizRule=null,$data=null)
71: {
72: return $this->createAuthItem($name,CAuthItem::TYPE_ROLE,$description,$bizRule,$data);
73: }
74:
75: /**
76: * Creates a task.
77: * This is a shortcut method to {@link IAuthManager::createAuthItem}.
78: * @param string $name the item name
79: * @param string $description the item description.
80: * @param string $bizRule the business rule associated with this item
81: * @param mixed $data additional data to be passed when evaluating the business rule
82: * @return CAuthItem the authorization item
83: */
84: public function createTask($name,$description='',$bizRule=null,$data=null)
85: {
86: return $this->createAuthItem($name,CAuthItem::TYPE_TASK,$description,$bizRule,$data);
87: }
88:
89: /**
90: * Creates an operation.
91: * This is a shortcut method to {@link IAuthManager::createAuthItem}.
92: * @param string $name the item name
93: * @param string $description the item description.
94: * @param string $bizRule the business rule associated with this item
95: * @param mixed $data additional data to be passed when evaluating the business rule
96: * @return CAuthItem the authorization item
97: */
98: public function createOperation($name,$description='',$bizRule=null,$data=null)
99: {
100: return $this->createAuthItem($name,CAuthItem::TYPE_OPERATION,$description,$bizRule,$data);
101: }
102:
103: /**
104: * Returns roles.
105: * This is a shortcut method to {@link IAuthManager::getAuthItems}.
106: * @param mixed $userId the user ID. If not null, only the roles directly assigned to the user
107: * will be returned. Otherwise, all roles will be returned.
108: * @return array roles (name=>CAuthItem)
109: */
110: public function getRoles($userId=null)
111: {
112: return $this->getAuthItems(CAuthItem::TYPE_ROLE,$userId);
113: }
114:
115: /**
116: * Returns tasks.
117: * This is a shortcut method to {@link IAuthManager::getAuthItems}.
118: * @param mixed $userId the user ID. If not null, only the tasks directly assigned to the user
119: * will be returned. Otherwise, all tasks will be returned.
120: * @return array tasks (name=>CAuthItem)
121: */
122: public function getTasks($userId=null)
123: {
124: return $this->getAuthItems(CAuthItem::TYPE_TASK,$userId);
125: }
126:
127: /**
128: * Returns operations.
129: * This is a shortcut method to {@link IAuthManager::getAuthItems}.
130: * @param mixed $userId the user ID. If not null, only the operations directly assigned to the user
131: * will be returned. Otherwise, all operations will be returned.
132: * @return array operations (name=>CAuthItem)
133: */
134: public function getOperations($userId=null)
135: {
136: return $this->getAuthItems(CAuthItem::TYPE_OPERATION,$userId);
137: }
138:
139: /**
140: * Executes the specified business rule.
141: * @param string $bizRule the business rule to be executed.
142: * @param array $params parameters passed to {@link IAuthManager::checkAccess}.
143: * @param mixed $data additional data associated with the authorization item or assignment.
144: * @return boolean whether the business rule returns true.
145: * If the business rule is empty, it will still return true.
146: */
147: public function executeBizRule($bizRule,$params,$data)
148: {
149: return $bizRule==='' || $bizRule===null || ($this->showErrors ? eval($bizRule)!=0 : @eval($bizRule)!=0);
150: }
151:
152: /**
153: * Checks the item types to make sure a child can be added to a parent.
154: * @param integer $parentType parent item type
155: * @param integer $childType child item type
156: * @throws CException if the item cannot be added as a child due to its incompatible type.
157: */
158: protected function checkItemChildType($parentType,$childType)
159: {
160: static $types=array('operation','task','role');
161: if($parentType < $childType)
162: throw new CException(Yii::t('yii','Cannot add an item of type "{child}" to an item of type "{parent}".',
163: array('{child}'=>$types[$childType], '{parent}'=>$types[$parentType])));
164: }
165: }
166: