Item.php 6.17 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 34 35 36 37 38 39 40 41 42
    const TYPE_OPERATION = 0;
    const TYPE_TASK = 1;
    const TYPE_ROLE = 2;

    /**
     * @var Manager the auth manager of this item
     */
    public $manager;
    /**
     * @var string the item description
     */
    public $description;
    /**
43
     * @var string name of the rule associated with this item
44
     */
45
    public $ruleName;
46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61
    /**
     * @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;

    private $_name;
    private $_oldName;

    /**
     * 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
     * of the [[Manager::checkAccess()]].
62 63
     * @param string $itemName the name of the item to be checked
     * @param array $params the parameters to be passed to business rule evaluation
64 65 66 67 68
     * @return boolean whether the specified item is within the hierarchy starting from this item.
     */
    public function checkAccess($itemName, $params = [])
    {
        Yii::trace('Checking permission: ' . $this->_name, __METHOD__);
69
        if ($this->manager->executeRule($this->ruleName, $params, $this->data)) {
70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103
            if ($this->_name == $itemName) {
                return true;
            }
            foreach ($this->manager->getItemChildren($this->_name) as $item) {
                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) {
            $this->_oldName = $this->_name;
            $this->_name = $value;
        }
    }

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

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

    /**
     * Returns a value indicating whether a child exists
128
     * @param string $name the child item name
129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148
     * @return boolean whether the child exists
     * @see Manager::hasItemChild
     */
    public function hasChild($name)
    {
        return $this->manager->hasItemChild($this->_name, $name);
    }

    /**
     * Returns the children of this item.
     * @return Item[] all child items of this item.
     * @see Manager::getItemChildren
     */
    public function getChildren()
    {
        return $this->manager->getItemChildren($this->_name);
    }

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

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

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

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

    /**
     * Saves an authorization item to persistent storage.
     */
    public function save()
    {
        $this->manager->saveItem($this, $this->_oldName);
        $this->_oldName = null;
    }
205
}