DbManager

API reference › yii › rbac › DbManager

class	yii\rbac\DbManager
Extends	BaseManager » yii\base\Component » yii\base\BaseObject
Implements	ManagerInterface, yii\base\Configurable
Since	2.0
Source	framework/rbac/DbManager.php

DbManager represents an authorization manager that stores authorization information in database.

The database connection is specified by $db. The database schema could be initialized by applying migration:

yii migrate --migrationPath=@yii/rbac/migrations/

If you don’t want to use migration and need SQL instead, files for all databases are in migrations directory.

You may change the names of the tables used to store the authorization and rule data by setting $itemTable, $itemChildTable, $assignmentTable and $ruleTable.

For more details and usage information on DbManager, see the guide article on security authorization.

Properties

Property	Type	Description	Defined by
$assignmentTable	string	The name of the table storing authorization item assignments. Default: '{{%auth_assignment}}'.	DbManager
$behaviors read-only	array<yii\base\Behavior<static>>	List of behaviors attached to this component.	yii\base\Component
$cache	yii\caching\CacheInterface|array|string|null	The cache used to improve RBAC performance. Default: null. Available since 2.0.3.	DbManager
$cacheKey	string	The key used to store RBAC data in cache Default: 'rbac'. Available since 2.0.3.	DbManager
$db	yii\db\Connection|array|string	The DB connection object or the application component ID of the DB connection. Default: 'db'.	DbManager
$defaultRoleInstances read-only	Role[]	Default roles.	BaseManager
$itemChildTable	string	The name of the table storing authorization item hierarchy. Default: '{{%auth_item_child}}'.	DbManager
$itemTable	string	The name of the table storing authorization items. Default: '{{%auth_item}}'.	DbManager
$permissions read-only	Permission[]	All permissions in the system.	BaseManager
$roles read-only	Role[]	All roles in the system.	BaseManager
$rolesCacheSuffix	string	The key used to store user RBAC roles in cache Default: 'roles'. Available since 2.0.48.	DbManager
$ruleTable	string	The name of the table storing rules. Default: '{{%auth_rule}}'.	DbManager
$checkAccessAssignments protected	array	User assignments (user id => Assignment[]) Default: [].	DbManager
$defaultRoles protected	array	A list of role names that are assigned to every user automatically without calling assign(). Default: [].	BaseManager
$items protected	Item[]|null	All auth items (name => Item) Default: null.	DbManager
$parents protected	array|null	Auth item parent-child relationships (childName => list of parents) Default: null.	DbManager
$rules protected	Rule[]|null	All auth rules (name => Rule) Default: null.	DbManager

Methods

Method	Description	Defined by
__construct()	Constructor.	yii\base\BaseObject
__call()	Calls the named method which is not a class method.	yii\base\Component
__clone()	This method is called after the object is created by cloning an existing one.	yii\base\Component
__get()	Returns the value of a component property.	yii\base\Component
__isset()	Checks if a property is set, i.e. defined and not null.	yii\base\Component
__set()	Sets the value of a component property.	yii\base\Component
__unset()	Sets a component property to be null.	yii\base\Component
add()	Adds a role, permission or rule to the RBAC system.	BaseManager
addChild()	Adds an item as a child of another item.	DbManager
assign()	Assigns a role to a user.	DbManager
attachBehavior()	Attaches a behavior to this component.	yii\base\Component
attachBehaviors()	Attaches a list of behaviors to the component.	yii\base\Component
behaviors()	Returns a list of behaviors that this component should behave as.	yii\base\Component
canAddChild()	Checks the possibility of adding a child to parent.	DbManager
canGetProperty()	Returns a value indicating whether a property can be read.	yii\base\Component
canSetProperty()	Returns a value indicating whether a property can be set.	yii\base\Component
checkAccess()		DbManager
className() static	Returns the fully qualified name of this class.	yii\base\BaseObject
createPermission()	Creates a new Permission object.	BaseManager
createRole()	Creates a new Role object.	BaseManager
detachBehavior()	Detaches a behavior from the component.	yii\base\Component
detachBehaviors()	Detaches all behaviors from the component.	yii\base\Component
ensureBehaviors()	Makes sure that the behaviors declared in behaviors() are attached to this component.	yii\base\Component
getAssignment()	Returns the assignment information regarding a role and a user.	DbManager
getAssignments()	Returns all role assignment information for the specified user.	DbManager
getBehavior()	Returns the named behavior object.	yii\base\Component
getBehaviors()	Returns all behaviors attached to this component.	yii\base\Component
getChildren()	Returns the child permissions and/or roles.	DbManager
getChildRoles()	Returns child roles of the role specified. Depth isn’t limited.	DbManager
getDefaultRoleInstances()	Returns defaultRoles as array of Role objects.	BaseManager
getDefaultRoles()	Get default roles	BaseManager
getPermission()	Returns the named permission.	BaseManager
getPermissions()	Returns all permissions in the system.	BaseManager
getPermissionsByRole()	Returns all permissions that the specified role represents.	DbManager
getPermissionsByUser()	Returns all permissions that the user has.	DbManager
getRole()	Returns the named role.	BaseManager
getRoles()	Returns all roles in the system.	BaseManager
getRolesByUser()	The roles returned by this method include the roles assigned via $defaultRoles.	DbManager
getRule()	Returns the rule of the specified name.	DbManager
getRules()	Returns all rules available in the system.	DbManager
getUserIdsByRole()	Returns all role assignment information for the specified role.	DbManager
hasChild()	Returns a value indicating whether the child already exists for the parent.	DbManager
hasEventHandlers()	Returns a value indicating whether there is any handler attached to the named event.	yii\base\Component
hasMethod()	Returns a value indicating whether a method is defined.	yii\base\Component
hasProperty()	Returns a value indicating whether a property is defined for this component.	yii\base\Component
init()	Initializes the application component.	DbManager
invalidateCache()		DbManager
loadFromCache()		DbManager
off()	Detaches an existing event handler from this component.	yii\base\Component
on()	Attaches an event handler to an event.	yii\base\Component
remove()	Removes a role, permission or rule from the RBAC system.	BaseManager
removeAll()	Removes all authorization data, including roles, permissions, rules, and assignments.	DbManager
removeAllAssignments()	Removes all role assignments.	DbManager
removeAllPermissions()	Removes all permissions.	DbManager
removeAllRoles()	Removes all roles.	DbManager
removeAllRules()	Removes all rules.	DbManager
removeChild()	Removes a child from its parent.	DbManager
removeChildren()	Removed all children form their parent.	DbManager
revoke()	Revokes a role from a user.	DbManager
revokeAll()	Revokes all roles from a user.	DbManager
setDefaultRoles()	Set default roles	BaseManager
trigger()	Triggers an event.	yii\base\Component
update()	Updates the specified role, permission or rule in the system.	BaseManager
addItem() protected	Adds an auth item to the RBAC system.	DbManager
addRule() protected	Adds a rule to the RBAC system.	DbManager
checkAccessFromCache() protected	Performs access check for the specified user based on the data loaded from cache.	DbManager
checkAccessRecursive() protected	Performs access check for the specified user.	DbManager
detectLoop() protected	Checks whether there is a loop in the authorization item hierarchy.	DbManager
executeRule() protected	Executes the rule associated with the specified auth item.	BaseManager
getChildrenList() protected	Returns the children for every parent.	DbManager
getChildrenRecursive() protected	Recursively finds all children and grand children of the specified item.	DbManager
getDirectPermissionsByUser() protected	Returns all permissions that are directly assigned to user.	DbManager
getInheritedPermissionsByUser() protected	Returns all permissions that the user inherits from the roles assigned to him.	DbManager
getItem() protected	Returns the named auth item.	DbManager
getItems() protected	Returns the items of the specified type.	DbManager
hasNoAssignments() protected	Checks whether array of $assignments is empty and $defaultRoles property is empty as well.	BaseManager
isEmptyUserId() protected	Check whether $userId is empty.	DbManager
populateItem() protected	Populates an auth item with the data fetched from database.	DbManager
removeAllItems() protected	Removes all auth items of the specified type.	DbManager
removeAllItemsManualCascade() protected	Removes all auth items of the given type without relying on FK enforcement.	DbManager
removeAllItemsSoftCascade() protected	Removes all auth items of the given type when FKs cascade for every direction except auth_item_child.child.	DbManager
removeAllRulesManualCascade() protected	Removes every auth rule without relying on FK enforcement.	DbManager
removeItem() protected	Removes an auth item from the RBAC system.	DbManager
removeItemManualCascade() protected	Removes an item without relying on FK enforcement.	DbManager
removeItemSoftCascade() protected	Removes an item when FKs cascade for every direction except auth_item_child.child.	DbManager
removeRule() protected	Removes a rule from the RBAC system.	DbManager
removeRuleManualCascade() protected	Removes a rule without relying on FK enforcement.	DbManager
requiresSoftCascade() protected	Returns whether the driver requires a partial PHP-level cleanup of auth_item_child rows whose child column references the affected item.	DbManager
supportsCascadeUpdate() protected	Returns whether the database performs cascade updates and deletes automatically (for example, via FK ON UPDATE CASCADE / ON DELETE CASCADE).	DbManager
updateItem() protected	Updates an auth item in the RBAC system.	DbManager
updateItemManualCascade() protected	Renames an item without relying on FK enforcement.	DbManager
updateItemSoftCascade() protected	Renames an item when FKs cascade for every direction except auth_item_child.child (MSSQL multi-path).	DbManager
updateRule() protected	Updates a rule to the RBAC system.	DbManager
updateRuleManualCascade() protected	Renames a rule without relying on FK enforcement.	DbManager

Property details

$assignmentTable

public string $assignmentTable = '{{%auth_assignment}}'

The name of the table storing authorization item assignments.

Defaults to “auth_assignment”.

$cache

public yii\caching\CacheInterface|array|string|null $cache = null

The cache used to improve RBAC performance.

This can be one of the following:

• an application component ID (e.g. cache)
• a configuration array
• a Cache object

When this is not set, it means caching is not enabled.

Note that by enabling RBAC cache, all auth items, rules and auth item parent-child relationships will be cached and loaded into memory. This will improve the performance of RBAC permission check. However, it does require extra memory and as a result may not be appropriate if your RBAC system contains too many auth items. You should seek other RBAC implementations (e.g. RBAC based on Redis storage) in this case.

Also note that if you modify RBAC items, rules or parent-child relationships from outside of this component, you have to manually call invalidateCache() to ensure data consistency.

Since

2.0.3

$db

public yii\db\Connection|array|string $db = 'db'

The DB connection object or the application component ID of the DB connection.

After the DbManager object is created, if you want to change this property, you should only assign it with a DB connection object. Starting from version 2.0.2, this can also be a configuration array for creating the object.

$itemChildTable

public string $itemChildTable = '{{%auth_item_child}}'

The name of the table storing authorization item hierarchy.

Defaults to “auth_item_child”.

$itemTable

public string $itemTable = '{{%auth_item}}'

The name of the table storing authorization items.

Defaults to “auth_item”.

$ruleTable

public string $ruleTable = '{{%auth_rule}}'

The name of the table storing rules.

Defaults to “auth_rule”.

Method details

addChild()

public function addChild(mixed $parent, mixed $child): bool

Adds an item as a child of another item.

Parameters

Parameter	Type	Description
$parent	mixed
$child	mixed

Returns

bool: Whether the child successfully added

Throws

• yii\base\Exception: if the parent-child relationship already exists or if a loop has been detected.

assign()

public function assign(mixed $role, mixed $userId): yii\rbac\Assignment

Assigns a role to a user.

Parameters

Parameter	Type	Description
$role	mixed
$userId	mixed	The user ID (see User::$id)

Returns

Assignment: The role assignment information.

Throws

• Exception: if the role has already been assigned to the user

canAddChild()

public function canAddChild(mixed $parent, mixed $child): bool

Checks the possibility of adding a child to parent.

Parameters

Parameter	Type	Description
$parent	mixed	The parent item
$child	mixed	The child item to be added to the hierarchy

Returns

bool: Possibility of adding

Since

2.0.8

checkAccess()

public function checkAccess(mixed $userId, mixed $permissionName, mixed $params = [])

Parameters

Parameter	Type	Description
$userId	mixed
$permissionName	mixed
$params	mixed

getAssignment()

public function getAssignment(mixed $roleName, mixed $userId): yii\rbac\Assignment|null

Returns the assignment information regarding a role and a user.

Parameters

Parameter	Type	Description
$roleName	mixed	The role name
$userId	mixed	The user ID (see User::$id)

Returns

Assignment|null: The assignment information. Null is returned if the role is not assigned to the user.

getAssignments()

public function getAssignments(mixed $userId): yii\rbac\Assignment[]

Returns all role assignment information for the specified user.

Parameters

Parameter	Type	Description
$userId	mixed	The user ID (see User::$id)

Returns

Assignment[]: The assignments indexed by role names. An empty array will be returned if there is no role assigned to the user.

getChildren()

public function getChildren(mixed $name): yii\rbac\Item[]

Returns the child permissions and/or roles.

Parameters

Parameter	Type	Description
$name	mixed	The parent name

Returns

Item[]: The child permissions and/or roles

getChildRoles()

public function getChildRoles(mixed $roleName): yii\rbac\Role[]

Returns child roles of the role specified. Depth isn’t limited.

Parameters

Parameter	Type	Description
$roleName	mixed	Name of the role to file child roles for

Returns

Role[]: Child roles. The array is indexed by the role names. First element is an instance of the parent Role itself.

Throws

• yii\base\InvalidArgumentException: if Role was not found that are getting by $roleName

Since

2.0.10

getPermissionsByRole()

public function getPermissionsByRole(mixed $roleName): yii\rbac\Permission[]

Returns all permissions that the specified role represents.

Parameters

Parameter	Type	Description
$roleName	mixed	The role name

Returns

Permission[]: All permissions that the role represents. The array is indexed by the permission names.

getPermissionsByUser()

public function getPermissionsByUser(mixed $userId): yii\rbac\Permission[]

Returns all permissions that the user has.

Parameters

Parameter	Type	Description
$userId	mixed	The user ID (see User::$id)

Returns

Permission[]: All permissions that the user has. The array is indexed by the permission names.

getRolesByUser()

public function getRolesByUser(mixed $userId): mixed

The roles returned by this method include the roles assigned via $defaultRoles.

Parameters

Parameter	Type	Description
$userId	mixed

Returns

mixed

getRule()

public function getRule(mixed $name): yii\rbac\Rule|null

Returns the rule of the specified name.

Parameters

Parameter	Type	Description
$name	mixed	The rule name

Returns

Rule|null: The rule object, or null if the specified name does not correspond to a rule.

getRules()

public function getRules(): yii\rbac\Rule[]

Returns all rules available in the system.

Returns

Rule[]: The rules indexed by the rule names

getUserIdsByRole()

public function getUserIdsByRole(string $roleName): string[]

Returns all role assignment information for the specified role.

Parameters

Parameter	Type	Description
$roleName	string

Returns

string[]: The ids. An empty array will be returned if role is not assigned to any user.

Since

2.0.7

hasChild()

public function hasChild(mixed $parent, mixed $child): bool

Returns a value indicating whether the child already exists for the parent.

Parameters

Parameter	Type	Description
$parent	mixed
$child	mixed

Returns

bool: Whether $child is already a child of $parent

init()

public function init(): mixed

Initializes the application component.

This method overrides the parent implementation by establishing the database connection.

Returns

mixed

invalidateCache()

public function invalidateCache(): mixed

Returns

mixed

loadFromCache()

public function loadFromCache(): mixed

Returns

mixed

removeAll()

public function removeAll(): mixed

Removes all authorization data, including roles, permissions, rules, and assignments.

Returns

mixed

removeAllAssignments()

public function removeAllAssignments(): mixed

Removes all role assignments.

Returns

mixed

removeAllPermissions()

public function removeAllPermissions(): mixed

Removes all permissions.

All parent child relations will be adjusted accordingly.

Returns

mixed

removeAllRoles()

public function removeAllRoles(): mixed

Removes all roles.

All parent child relations will be adjusted accordingly.

Returns

mixed

removeAllRules()

public function removeAllRules(): mixed

Removes all rules.

All roles and permissions which have rules will be adjusted accordingly.

Returns

mixed

removeChild()

public function removeChild(mixed $parent, mixed $child): bool

Removes a child from its parent.

Note, the child item is not deleted. Only the parent-child relationship is removed.

Parameters

Parameter	Type	Description
$parent	mixed
$child	mixed

Returns

bool: Whether the removal is successful

removeChildren()

public function removeChildren(mixed $parent): bool

Removed all children form their parent.

Note, the children items are not deleted. Only the parent-child relationships are removed.

Parameters

Parameter	Type	Description
$parent	mixed

Returns

bool: Whether the removal is successful

revoke()

public function revoke(mixed $role, mixed $userId): bool

Revokes a role from a user.

Parameters

Parameter	Type	Description
$role	mixed
$userId	mixed	The user ID (see User::$id)

Returns

bool: Whether the revoking is successful

revokeAll()

public function revokeAll(mixed $userId): bool

Revokes all roles from a user.

Parameters

Parameter	Type	Description
$userId	mixed	The user ID (see User::$id)

Returns

bool: Whether the revoking is successful

addItem()

protected function addItem(mixed $item): bool

Adds an auth item to the RBAC system.

Parameters

Parameter	Type	Description
$item	mixed	The item to add

Returns

bool: Whether the auth item is successfully added to the system

Throws

• Exception: if data validation or saving fails (such as the name of the role or permission is not unique)

addRule()

protected function addRule(mixed $rule): bool

Adds a rule to the RBAC system.

Parameters

Parameter	Type	Description
$rule	mixed	The rule to add

Returns

bool: Whether the rule is successfully added to the system

Throws

• Exception: if data validation or saving fails (such as the name of the rule is not unique)

checkAccessFromCache()

protected function checkAccessFromCache(string|int $user, string $itemName, array $params, yii\rbac\Assignment[] $assignments): bool

Performs access check for the specified user based on the data loaded from cache.

This method is internally called by checkAccess() when $cache is enabled.

Parameters

Parameter	Type	Description
$user	string|int	The user ID. This should can be either an integer or a string representing the unique identifier of a user. See User::$id.
$itemName	string	The name of the operation that need access check
$params	array	Name-value pairs that would be passed to rules associated with the tasks and roles assigned to the user. A param with name ‘user’ is added to this array, which holds the value of $userId.
$assignments	Assignment[]	The assignments to the specified user

Returns

bool: Whether the operations can be performed by the user.

Since

2.0.3

checkAccessRecursive()

protected function checkAccessRecursive(string|int $user, string $itemName, array $params, yii\rbac\Assignment[] $assignments): bool

Performs access check for the specified user.

This method is internally called by checkAccess().

Parameters

Parameter	Type	Description
$user	string|int	The user ID. This should can be either an integer or a string representing the unique identifier of a user. See User::$id.
$itemName	string	The name of the operation that need access check
$params	array	Name-value pairs that would be passed to rules associated with the tasks and roles assigned to the user. A param with name ‘user’ is added to this array, which holds the value of $userId.
$assignments	Assignment[]	The assignments to the specified user

Returns

bool: Whether the operations can be performed by the user.

detectLoop()

protected function detectLoop(yii\rbac\Item $parent, yii\rbac\Item $child): bool

Checks whether there is a loop in the authorization item hierarchy.

Parameters

Parameter	Type	Description
$parent	Item	The parent item
$child	Item	The child item to be added to the hierarchy

Returns

bool: Whether a loop exists

getChildrenList()

protected function getChildrenList(): array

Returns the children for every parent.

Returns

array: The children list. Each array key is a parent item name, and the corresponding array value is a list of child item names.

getChildrenRecursive()

protected function getChildrenRecursive(string $name, array $childrenList, array &$result): mixed

Recursively finds all children and grand children of the specified item.

Parameters

Parameter	Type	Description
$name	string	The name of the item whose children are to be looked for.
$childrenList	array	The child list built via getChildrenList()
$result	array	The children and grand children (in array keys)

Returns

mixed

getDirectPermissionsByUser()

protected function getDirectPermissionsByUser(string|int $userId): yii\rbac\Permission[]

Returns all permissions that are directly assigned to user.

Parameters

Parameter	Type	Description
$userId	string|int	The user ID (see User::$id)

Returns

Permission[]: All direct permissions that the user has. The array is indexed by the permission names.

Since

2.0.7

getInheritedPermissionsByUser()

protected function getInheritedPermissionsByUser(string|int $userId): yii\rbac\Permission[]

Returns all permissions that the user inherits from the roles assigned to him.

Parameters

Parameter	Type	Description
$userId	string|int	The user ID (see User::$id)

Returns

Permission[]: All inherited permissions that the user has. The array is indexed by the permission names.

Since

2.0.7

getItem()

protected function getItem(mixed $name): yii\rbac\Item|null

Returns the named auth item.

Parameters

Parameter	Type	Description
$name	mixed	The auth item name.

Returns

Item|null: The auth item corresponding to the specified name. Null is returned if no such item.

getItems()

protected function getItems(mixed $type): ($type is yii\rbac\Item::TYPE_ROLE ? yii\rbac\Role[] : yii\rbac\Permission[])

Returns the items of the specified type.

Parameters

Parameter	Type	Description
$type	mixed	The auth item type (either Item::TYPE_ROLE or Item::TYPE_PERMISSION

Returns

($type is Item::TYPE_ROLE ? Role[] : Permission[]): The auth items of the specified type.

isEmptyUserId()

protected function isEmptyUserId(mixed $userId): bool

Check whether $userId is empty.

Parameters

Parameter	Type	Description
$userId	mixed

Returns

bool

Since

2.0.26

populateItem()

protected function populateItem(array $row): yii\rbac\Item

Populates an auth item with the data fetched from database.

Parameters

Parameter	Type	Description
$row	array	The data from the auth item table

Returns

Item: The populated auth item instance (either Role or Permission)

removeAllItems()

protected function removeAllItems(int $type): mixed

Removes all auth items of the specified type.

Parameters

Parameter	Type	Description
$type	int	The auth item type (either Item::TYPE_PERMISSION or Item::TYPE_ROLE).

Returns

mixed

removeAllItemsManualCascade()

protected function removeAllItemsManualCascade(int $type): void

Removes all auth items of the given type without relying on FK enforcement.

Used by SQLite. Clears referencing rows in auth_item_child (both directions) and auth_assignment via a correlated subquery, then deletes the items themselves.

Parameters

Parameter	Type	Description
$type	int	The auth item type (either Item::TYPE_PERMISSION or Item::TYPE_ROLE).

Since

22.0

removeAllItemsSoftCascade()

protected function removeAllItemsSoftCascade(int $type): void

Removes all auth items of the given type when FKs cascade for every direction except auth_item_child.child.

Used by MSSQL. Clears the multi-path direction via a correlated subquery; native cascade handles the rest.

Parameters

Parameter	Type	Description
$type	int	The auth item type (either Item::TYPE_PERMISSION or Item::TYPE_ROLE).

Since

22.0

removeAllRulesManualCascade()

protected function removeAllRulesManualCascade(): void

Removes every auth rule without relying on FK enforcement.

Used by SQLite. Nulls out every auth_item.rule_name reference before deleting all rule rows.

Since

22.0

removeItem()

protected function removeItem(mixed $item): bool

Removes an auth item from the RBAC system.

Parameters

Parameter	Type	Description
$item	mixed	The item to remove

Returns

bool: Whether the role or permission is successfully removed

Throws

• Exception: if data validation or saving fails (such as the name of the role or permission is not unique)

removeItemManualCascade()

protected function removeItemManualCascade(yii\rbac\Item $item): void

Removes an item without relying on FK enforcement.

Used by SQLite where foreign keys are not enforced. Deletes referencing rows in auth_item_child (both directions) and auth_assignment before deleting the item itself, all inside one transaction so a partial failure rolls back.

Parameters

Parameter	Type	Description
$item	Item	The item to remove.

Since

22.0

removeItemSoftCascade()

protected function removeItemSoftCascade(yii\rbac\Item $item): void

Removes an item when FKs cascade for every direction except auth_item_child.child.

Used by MSSQL where the multi-path constraint forces the auth_item_child.child FK to NO ACTION. That direction is cleared explicitly; the rest (auth_item_child.parent, auth_assignment) cascades natively.

Parameters

Parameter	Type	Description
$item	Item	The item to remove.

Since

22.0

removeRule()

protected function removeRule(mixed $rule): bool

Removes a rule from the RBAC system.

Parameters

Parameter	Type	Description
$rule	mixed	The rule to remove

Returns

bool: Whether the rule is successfully removed

Throws

• Exception: if data validation or saving fails (such as the name of the rule is not unique)

removeRuleManualCascade()

protected function removeRuleManualCascade(yii\rbac\Rule $rule): void

Removes a rule without relying on FK enforcement.

Used by SQLite. Nulls out auth_item.rule_name references before deleting the rule itself.

Parameters

Parameter	Type	Description
$rule	Rule	The rule to remove.

Since

22.0

requiresSoftCascade()

protected function requiresSoftCascade(): bool

Returns whether the driver requires a partial PHP-level cleanup of auth_item_child rows whose child column references the affected item.

MSSQL rejects ON DELETE CASCADE / ON UPDATE CASCADE on the second FK from auth_item_child to auth_item.name (multi-path constraint), so the child direction is left as NO ACTION in the schema and must be cleaned up explicitly before the parent row is deleted or renamed. The other RBAC FKs cascade natively.

Default returns true for MSSQL drivers. Subclasses can override to register custom drivers with the same limitation.

Returns

bool: Whether the auth_item_child.child direction must be handled in PHP.

Since

22.0

supportsCascadeUpdate()

protected function supportsCascadeUpdate(): bool

Returns whether the database performs cascade updates and deletes automatically (for example, via FK ON UPDATE CASCADE / ON DELETE CASCADE).

Default returns false only for SQLite (no FK enforcement). MySQL, PostgreSQL, and MSSQL return true because their RBAC schemas declare ON UPDATE CASCADE / ON DELETE CASCADE (with the multi-path exception on auth_item_child.child for MSSQL — see requiresSoftCascade()). Subclasses can override to register custom drivers.

Returns

bool: Whether the database supports cascading update and delete.

updateItem()

protected function updateItem(mixed $name, mixed $item): bool

Updates an auth item in the RBAC system.

Parameters

Parameter	Type	Description
$name	mixed	The name of the item being updated
$item	mixed	The updated item

Returns

bool: Whether the auth item is successfully updated

Throws

• Exception: if data validation or saving fails (such as the name of the role or permission is not unique)

updateItemManualCascade()

protected function updateItemManualCascade(string $oldName, yii\rbac\Item $item): void

Renames an item without relying on FK enforcement.

Used by SQLite. Directly updates referencing rows in auth_item_child (both directions) and auth_assignment before renaming the item itself, all inside one transaction.

Parameters

Parameter	Type	Description
$oldName	string	The current name of the item.
$item	Item	The item carrying the new field values.

Since

22.0

updateItemSoftCascade()

protected function updateItemSoftCascade(string $oldName, yii\rbac\Item $item): void

Renames an item when FKs cascade for every direction except auth_item_child.child (MSSQL multi-path).

Snapshots the affected rows, deletes them, renames the parent (the DB cascades auth_item_child.parent and auth_assignment.item_name), and re-inserts the snapshot under the new name.

Parameters

Parameter	Type	Description
$oldName	string	The current name of the item.
$item	Item	The item carrying the new field values.

Since

22.0

updateRule()

protected function updateRule(mixed $name, mixed $rule): bool

Updates a rule to the RBAC system.

Parameters

Parameter	Type	Description
$name	mixed	The name of the rule being updated
$rule	mixed	The updated rule

Returns

bool: Whether the rule is successfully updated

Throws

• Exception: if data validation or saving fails (such as the name of the rule is not unique)

updateRuleManualCascade()

protected function updateRuleManualCascade(string $oldName, yii\rbac\Rule $rule): void

Renames a rule without relying on FK enforcement.

Used by SQLite. Directly updates auth_item.rule_name references before renaming the rule itself.

Parameters

Parameter	Type	Description
$oldName	string	The current name of the rule.
$rule	Rule	The rule carrying the new field values.

Since

22.0