Item.php 6.18 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 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61
    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;
    /**
     * @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;

    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 69 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
     * @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__);
        if ($this->manager->executeBizRule($this->bizRule, $params, $this->data)) {
            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 151 152 153
     * @param mixed $userId the user ID (see [[\yii\web\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
     * @return Assignment the authorization assignment information.
154 155 156 157 158 159 160 161 162 163
     * @throws \yii\base\Exception if the item has already been assigned to the user
     * @see Manager::assign
     */
    public function assign($userId, $bizRule = null, $data = null)
    {
        return $this->manager->assign($userId, $this->_name, $bizRule, $data);
    }

    /**
     * Revokes an authorization assignment from a user.
164
     * @param mixed $userId the user ID (see [[\yii\web\User::id]])
165 166 167 168 169 170 171 172 173 174
     * @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.
175
     * @param mixed $userId the user ID (see [[\yii\web\User::id]])
176 177 178 179 180 181 182 183 184 185
     * @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.
186
     * @param mixed $userId the user ID (see [[\yii\web\User::id]])
187
     * @return Assignment the item assignment information. Null is returned if
188
     * this item is not assigned to the user.
189 190 191 192 193 194 195 196 197 198 199 200 201 202 203
     * @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;
    }
204
}