Item.php 5.56 KB
Newer Older
1 2 3 4 5 6 7
<?php
/**
 * @link http://www.yiiframework.com/
 * @copyright Copyright (c) 2008 Yii Software LLC
 * @license http://www.yiiframework.com/license/
 */

8
namespace yii\rbac;
9 10 11 12 13

use Yii;
use yii\base\Object;

/**
14 15 16 17 18 19 20
 * 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.
 *
21
 * @property Item[] $children All child items of this item. This property is read-only.
22 23
 * @property string $name The item name.
 *
24 25 26 27
 * @author Qiang Xue <qiang.xue@gmail.com>
 * @author Alexander Kochetov <creocoder@gmail.com>
 * @since 2.0
 */
28
class Item extends Object
29 30 31 32 33
{
	const TYPE_OPERATION = 0;
	const TYPE_TASK = 1;
	const TYPE_ROLE = 2;

Qiang Xue committed
34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54
	/**
	 * @var Manager the auth manager of this item
	 */
	public $manager;
	/**
	 * @var string the item description
	 */
	public $description;
	/**
	 * @var string the business rule associated with this item
	 */
	public $bizRule;
	/**
	 * @var mixed the additional data associated with this item
	 */
	public $data;
	/**
	 * @var integer the authorization item type. This could be 0 (operation), 1 (task) or 2 (role).
	 */
	public $type;

55
	private $_name;
56
	private $_oldName;
57 58 59 60 61


	/**
	 * Checks to see if the specified item is within the hierarchy starting from this item.
	 * This method is expected to be internally used by the actual implementations
62
	 * of the [[Manager::checkAccess()]].
63 64 65 66 67 68 69
	 * @param string $itemName the name of the item to be checked
	 * @param array $params the parameters to be passed to business rule evaluation
	 * @return boolean whether the specified item is within the hierarchy starting from this item.
	 */
	public function checkAccess($itemName, $params = array())
	{
		Yii::trace('Checking permission: ' . $this->_name, __METHOD__);
Qiang Xue committed
70
		if ($this->manager->executeBizRule($this->bizRule, $params, $this->data)) {
71 72 73
			if ($this->_name == $itemName) {
				return true;
			}
Qiang Xue committed
74
			foreach ($this->manager->getItemChildren($this->_name) as $item) {
75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96
				if ($item->checkAccess($itemName, $params)) {
					return true;
				}
			}
		}
		return false;
	}

	/**
	 * @return string the item name
	 */
	public function getName()
	{
		return $this->_name;
	}

	/**
	 * @param string $value the item name
	 */
	public function setName($value)
	{
		if ($this->_name !== $value) {
97
			$this->_oldName = $this->_name;
98 99 100 101 102 103 104 105 106
			$this->_name = $value;
		}
	}

	/**
	 * Adds a child item.
	 * @param string $name the name of the child item
	 * @return boolean whether the item is added successfully
	 * @throws \yii\base\Exception if either parent or child doesn't exist or if a loop has been detected.
107
	 * @see Manager::addItemChild
108 109 110
	 */
	public function addChild($name)
	{
Qiang Xue committed
111
		return $this->manager->addItemChild($this->_name, $name);
112 113 114 115 116 117 118
	}

	/**
	 * Removes a child item.
	 * Note, the child item is not deleted. Only the parent-child relationship is removed.
	 * @param string $name the child item name
	 * @return boolean whether the removal is successful
119
	 * @see Manager::removeItemChild
120 121 122
	 */
	public function removeChild($name)
	{
Qiang Xue committed
123
		return $this->manager->removeItemChild($this->_name, $name);
124 125 126 127 128 129
	}

	/**
	 * Returns a value indicating whether a child exists
	 * @param string $name the child item name
	 * @return boolean whether the child exists
130
	 * @see Manager::hasItemChild
131 132 133
	 */
	public function hasChild($name)
	{
Qiang Xue committed
134
		return $this->manager->hasItemChild($this->_name, $name);
135 136 137 138
	}

	/**
	 * Returns the children of this item.
139
	 * @return Item[] all child items of this item.
140
	 * @see Manager::getItemChildren
141 142 143
	 */
	public function getChildren()
	{
Qiang Xue committed
144
		return $this->manager->getItemChildren($this->_name);
145 146 147 148 149 150 151 152
	}

	/**
	 * Assigns this item to a user.
	 * @param mixed $userId the user ID (see [[User::id]])
	 * @param string $bizRule the business rule to be executed when [[checkAccess()]] is called
	 * for this particular authorization item.
	 * @param mixed $data additional data associated with this assignment
153
	 * @return Assignment the authorization assignment information.
154
	 * @throws \yii\base\Exception if the item has already been assigned to the user
155
	 * @see Manager::assign
156 157 158
	 */
	public function assign($userId, $bizRule = null, $data = null)
	{
Qiang Xue committed
159
		return $this->manager->assign($userId, $this->_name, $bizRule, $data);
160 161 162 163 164 165
	}

	/**
	 * Revokes an authorization assignment from a user.
	 * @param mixed $userId the user ID (see [[User::id]])
	 * @return boolean whether removal is successful
166
	 * @see Manager::revoke
167 168 169
	 */
	public function revoke($userId)
	{
Qiang Xue committed
170
		return $this->manager->revoke($userId, $this->_name);
171 172 173 174 175 176
	}

	/**
	 * Returns a value indicating whether this item has been assigned to the user.
	 * @param mixed $userId the user ID (see [[User::id]])
	 * @return boolean whether the item has been assigned to the user.
177
	 * @see Manager::isAssigned
178 179 180
	 */
	public function isAssigned($userId)
	{
Qiang Xue committed
181
		return $this->manager->isAssigned($userId, $this->_name);
182 183 184 185 186
	}

	/**
	 * Returns the item assignment information.
	 * @param mixed $userId the user ID (see [[User::id]])
187
	 * @return Assignment the item assignment information. Null is returned if
188
	 * this item is not assigned to the user.
189
	 * @see Manager::getAssignment
190 191 192
	 */
	public function getAssignment($userId)
	{
Qiang Xue committed
193
		return $this->manager->getAssignment($userId, $this->_name);
194
	}
195 196 197 198 199 200

	/**
	 * Saves an authorization item to persistent storage.
	 */
	public function save()
	{
Qiang Xue committed
201
		$this->manager->saveItem($this, $this->_oldName);
202 203
		unset($this->_oldName);
	}
204
}