AccessRule

API reference › yii › filters › AccessRule

class	yii\filters\AccessRule
Extends	yii\base\Component » yii\base\BaseObject
Implements	yii\base\Configurable
Since	2.0
Source	framework/filters/AccessRule.php

This class represents an access rule defined by the AccessControl action filter.

Properties

Property	Type	Description	Defined by
$actions	array|null	List of action IDs that this rule applies to. Default: null.	AccessRule
$allow	bool	Whether this is an ‘allow’ rule or ‘deny’ rule. Default: false.	AccessRule
$behaviors read-only	array<yii\base\Behavior<static>>	List of behaviors attached to this component.	yii\base\Component
$controllers	array|null	List of the controller IDs that this rule applies to. Default: null.	AccessRule
$denyCallback	callable|null	A callback that will be called if this rule determines the access to the current action should be denied. Default: null.	AccessRule
$ips	array|null	List of user IP addresses that this rule applies to. Default: null.	AccessRule
$matchCallback	callable	A callback that will be called to determine if the rule should be applied. Default: null.	AccessRule
$permissions	array|null	List of RBAC (Role-Based Access Control) permissions that this rules applies to. User::can() will be called to check access. Default: null. Available since 2.0.12.	AccessRule
$roleParams	array|object|Closure	Parameters to pass to the User::can() function for evaluating user permissions in $roles. Default: []. Available since 2.0.12.	AccessRule
$roles	array|null	List of roles that this rule applies to (requires properly configured User component). Default: null.	AccessRule
$verbs	array|null	List of request methods (e.g. GET, POST) that this rule applies to. Default: null.	AccessRule

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
allows()	Checks whether the Web user is allowed to perform the specified action.	AccessRule
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
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
className() static	Returns the fully qualified name of this class.	yii\base\BaseObject
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
getBehavior()	Returns the named behavior object.	yii\base\Component
getBehaviors()	Returns all behaviors attached to this component.	yii\base\Component
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 object.	yii\base\BaseObject
off()	Detaches an existing event handler from this component.	yii\base\Component
on()	Attaches an event handler to an event.	yii\base\Component
trigger()	Triggers an event.	yii\base\Component
matchAction() protected		AccessRule
matchController() protected		AccessRule
matchCustom() protected		AccessRule
matchIP() protected		AccessRule
matchRole() protected		AccessRule
matchVerb() protected		AccessRule

Property details

$actions

public array|null $actions = null

List of action IDs that this rule applies to.

The comparison is case-sensitive. If not set or empty, it means this rule applies to all actions.

$controllers

public array|null $controllers = null

List of the controller IDs that this rule applies to.

The comparison uses Controller::$uniqueId, so each controller ID is prefixed with the module ID (if any). For a product controller in the application, you would specify this property like ['product'] and if that controller is located in a shop module, this would be ['shop/product'].

The comparison is case-sensitive.

If not set or empty, it means this rule applies to all controllers.

Since version 2.0.12 controller IDs can be specified as wildcards, e.g. module/*.

$denyCallback

public callable|null $denyCallback = null

A callback that will be called if this rule determines the access to the current action should be denied.

This is the case when this rule matches and $allow is set to false.

If not set, the behavior will be determined by AccessControl, either using AccessControl::denyAccess() or AccessControl::$denyCallback, if configured.

The signature of the callback should be as follows:

function ($rule, $action)

where $rule is this rule, and $action is the current action object.

$ips

public array|null $ips = null

List of user IP addresses that this rule applies to.

An IP address can contain the wildcard * at the end so that it matches IP addresses with the same prefix. For example, ‘192.168.*’ matches all IP addresses in the segment ‘192.168.’. It may also contain a pattern/mask like ‘172.16.0.0/12’ which would match all IPs from the 20-bit private network block in RFC1918. If not set or empty, it means this rule applies to all IP addresses.

$matchCallback

public callable $matchCallback = null

A callback that will be called to determine if the rule should be applied.

The signature of the callback should be as follows:

function ($rule, $action)

where $rule is this rule, and $action is the current action object. The callback should return a boolean value indicating whether this rule should be applied.

$permissions

public array|null $permissions = null

List of RBAC (Role-Based Access Control) permissions that this rules applies to. User::can() will be called to check access.

If this property is not set or empty, it means this rule applies regardless of permissions.

Since

2.0.12

$roleParams

public array|object|Closure $roleParams = []

Parameters to pass to the User::can() function for evaluating user permissions in $roles.

If this is an array, it will be passed directly to User::can(). For example for passing an ID from the current request, you may use the following:

['postId' => Yii::$app->request->get('id')]

You may also specify a closure that returns an array. This can be used to evaluate the array values only if they are needed, for example when a model needs to be loaded like in the following code:

'rules' => [
    [
        'allow' => true,
        'actions' => ['update'],
        'roles' => ['updatePost'],
        'roleParams' => function($rule) {
            return ['post' => Post::findOne(Yii::$app->request->get('id'))];
        },
    ],
],

A reference to the AccessRule instance will be passed to the closure as the first parameter.

Since

2.0.12

$roles

public array|null $roles = null

List of roles that this rule applies to (requires properly configured User component).

Two special roles are recognized, and they are checked via User::$isGuest:

• ?: matches a guest user (not authenticated yet)
• @: matches an authenticated user

If you are using RBAC (Role-Based Access Control), you may also specify role names. In this case, User::can() will be called to check access.

Note that it is preferred to check for permissions instead.

If this property is not set or empty, it means this rule applies regardless of roles.

$verbs

public array|null $verbs = null

List of request methods (e.g. GET, POST) that this rule applies to.

If not set or empty, it means this rule applies to all request methods.

Method details

allows()

public function allows(yii\base\Action $action, yii\web\User|false $user, yii\web\Request $request): bool|null

Checks whether the Web user is allowed to perform the specified action.

Parameters

Parameter	Type	Description
$action	yii\base\Action	The action to be performed
$user	yii\web\User|false	The user object or false in case of detached User component
$request	yii\web\Request

Returns

bool|null: true if the user is allowed, false if the user is denied, null if the rule does not apply to the user

matchAction()

protected function matchAction(yii\base\Action $action): bool

Parameters

Parameter	Type	Description
$action	yii\base\Action	The action

Returns

bool: Whether the rule applies to the action

matchController()

protected function matchController(yii\base\Controller|null $controller): bool

Parameters

Parameter	Type	Description
$controller	yii\base\Controller|null	The controller, or null when the action runs as a standalone action dispatched by Module::$actionMap (since 22.0).

Returns

bool: Whether the rule applies to the controller.

matchCustom()

protected function matchCustom(yii\base\Action $action): bool

Parameters

Parameter	Type	Description
$action	yii\base\Action	The action to be performed

Returns

bool: Whether the rule should be applied

matchIP()

protected function matchIP(string|null $ip): bool

Parameters

Parameter	Type	Description
$ip	string|null	The IP address

Returns

bool: Whether the rule applies to the IP address

matchRole()

protected function matchRole(yii\web\User $user): bool

Parameters

Parameter	Type	Description
$user	yii\web\User	The user object

Returns

bool: Whether the rule applies to the role

Throws

• yii\base\InvalidConfigException: if User component is detached

matchVerb()

protected function matchVerb(string $verb): bool

Parameters

Parameter	Type	Description
$verb	string	The request method.

Returns

bool: Whether the rule applies to the request