# AccessRule

> This class represents an access rule defined by the yii\filters\AccessControl action filter.

[API reference](/docs/api/index.md) › [yii](/docs/api/yii/index.md) › [filters](/docs/api/yii/filters/index.md) › AccessRule

| class | `yii\filters\AccessRule` |
| --- | --- |
| Extends | [`yii\base\Component`](/docs/api/yii/base/component/index.md) » [`yii\base\BaseObject`](/docs/api/yii/base/baseobject/index.md) |
| Implements | [`yii\base\Configurable`](/docs/api/yii/base/configurable/index.md) |
| Since | 2.0 |
| Source | [`framework/filters/AccessRule.php`](https://github.com/yiisoft/yii2/blob/22.0/framework/filters/AccessRule.php#L30) |

This class represents an access rule defined by the [`AccessControl`](/docs/api/yii/filters/accesscontrol/index.md) action filter.

## Properties

| Property | Type | Description | Defined by |
| --- | --- | --- | --- |
| [`$actions`](#property-actions) | `array\|null` | List of action IDs that this rule applies to. Default: `null`. | `AccessRule` |
| <span id="property-allow"></span>`$allow` | `bool` | Whether this is an 'allow' rule or 'deny' rule. Default: `false`. | `AccessRule` |
| <span id="property-behaviors"></span>[`$behaviors`](/docs/api/yii/base/component/index.md#property-behaviors) read-only | `array<`[`yii\base\Behavior`](/docs/api/yii/base/behavior/index.md)`<static>>` | List of behaviors attached to this component. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| [`$controllers`](#property-controllers) | `array\|null` | List of the controller IDs that this rule applies to. Default: `null`. | `AccessRule` |
| [`$denyCallback`](#property-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`](#property-ips) | `array\|null` | List of user IP addresses that this rule applies to. Default: `null`. | `AccessRule` |
| [`$matchCallback`](#property-matchCallback) | `callable` | A callback that will be called to determine if the rule should be applied. Default: `null`. | `AccessRule` |
| [`$permissions`](#property-permissions) | `array\|null` | List of RBAC (Role-Based Access Control) permissions that this rules applies to. [`User::can()`](/docs/api/yii/web/user/index.md#method-can) will be called to check access. Default: `null`. Available since 2.0.12. | `AccessRule` |
| [`$roleParams`](#property-roleParams) | `array\|object\|`[`Closure`](https://www.php.net/manual/en/class.closure.php) | Parameters to pass to the [`User::can()`](/docs/api/yii/web/user/index.md#method-can) function for evaluating user permissions in [`$roles`](/docs/api/yii/filters/accessrule/index.md#property-roles). Default: `[]`. Available since 2.0.12. | `AccessRule` |
| [`$roles`](#property-roles) | `array\|null` | List of roles that this rule applies to (requires properly configured User component). Default: `null`. | `AccessRule` |
| [`$verbs`](#property-verbs) | `array\|null` | List of request methods (e.g. `GET`, `POST`) that this rule applies to. Default: `null`. | `AccessRule` |

## Methods

| Method | Description | Defined by |
| --- | --- | --- |
| <span id="method-__construct"></span>[`__construct()`](/docs/api/yii/base/baseobject/index.md#method-__construct) | Constructor. | [`yii\base\BaseObject`](/docs/api/yii/base/baseobject/index.md) |
| <span id="method-__call"></span>[`__call()`](/docs/api/yii/base/component/index.md#method-__call) | Calls the named method which is not a class method. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="method-__clone"></span>[`__clone()`](/docs/api/yii/base/component/index.md#method-__clone) | This method is called after the object is created by cloning an existing one. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="method-__get"></span>[`__get()`](/docs/api/yii/base/component/index.md#method-__get) | Returns the value of a component property. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="method-__isset"></span>[`__isset()`](/docs/api/yii/base/component/index.md#method-__isset) | Checks if a property is set, i.e. defined and not null. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="method-__set"></span>[`__set()`](/docs/api/yii/base/component/index.md#method-__set) | Sets the value of a component property. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="method-__unset"></span>[`__unset()`](/docs/api/yii/base/component/index.md#method-__unset) | Sets a component property to be null. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| [`allows()`](#method-allows) | Checks whether the Web user is allowed to perform the specified action. | `AccessRule` |
| <span id="method-attachBehavior"></span>[`attachBehavior()`](/docs/api/yii/base/component/index.md#method-attachBehavior) | Attaches a behavior to this component. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="method-attachBehaviors"></span>[`attachBehaviors()`](/docs/api/yii/base/component/index.md#method-attachBehaviors) | Attaches a list of behaviors to the component. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="method-behaviors"></span>[`behaviors()`](/docs/api/yii/base/component/index.md#method-behaviors) | Returns a list of behaviors that this component should behave as. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="method-canGetProperty"></span>[`canGetProperty()`](/docs/api/yii/base/component/index.md#method-canGetProperty) | Returns a value indicating whether a property can be read. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="method-canSetProperty"></span>[`canSetProperty()`](/docs/api/yii/base/component/index.md#method-canSetProperty) | Returns a value indicating whether a property can be set. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="method-className"></span>[`className()`](/docs/api/yii/base/baseobject/index.md#method-className) static | Returns the fully qualified name of this class. | [`yii\base\BaseObject`](/docs/api/yii/base/baseobject/index.md) |
| <span id="method-detachBehavior"></span>[`detachBehavior()`](/docs/api/yii/base/component/index.md#method-detachBehavior) | Detaches a behavior from the component. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="method-detachBehaviors"></span>[`detachBehaviors()`](/docs/api/yii/base/component/index.md#method-detachBehaviors) | Detaches all behaviors from the component. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="method-ensureBehaviors"></span>[`ensureBehaviors()`](/docs/api/yii/base/component/index.md#method-ensureBehaviors) | Makes sure that the behaviors declared in [`behaviors()`](/docs/api/yii/base/component/index.md#method-behaviors) are attached to this component. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="method-getBehavior"></span>[`getBehavior()`](/docs/api/yii/base/component/index.md#method-getBehavior) | Returns the named behavior object. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="method-getBehaviors"></span>[`getBehaviors()`](/docs/api/yii/base/component/index.md#method-getBehaviors) | Returns all behaviors attached to this component. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="method-hasEventHandlers"></span>[`hasEventHandlers()`](/docs/api/yii/base/component/index.md#method-hasEventHandlers) | Returns a value indicating whether there is any handler attached to the named event. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="method-hasMethod"></span>[`hasMethod()`](/docs/api/yii/base/component/index.md#method-hasMethod) | Returns a value indicating whether a method is defined. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="method-hasProperty"></span>[`hasProperty()`](/docs/api/yii/base/component/index.md#method-hasProperty) | Returns a value indicating whether a property is defined for this component. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="method-init"></span>[`init()`](/docs/api/yii/base/baseobject/index.md#method-init) | Initializes the object. | [`yii\base\BaseObject`](/docs/api/yii/base/baseobject/index.md) |
| <span id="method-off"></span>[`off()`](/docs/api/yii/base/component/index.md#method-off) | Detaches an existing event handler from this component. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="method-on"></span>[`on()`](/docs/api/yii/base/component/index.md#method-on) | Attaches an event handler to an event. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="method-trigger"></span>[`trigger()`](/docs/api/yii/base/component/index.md#method-trigger) | Triggers an event. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| [`matchAction()`](#method-matchAction) protected |  | `AccessRule` |
| [`matchController()`](#method-matchController) protected |  | `AccessRule` |
| [`matchCustom()`](#method-matchCustom) protected |  | `AccessRule` |
| [`matchIP()`](#method-matchIP) protected |  | `AccessRule` |
| [`matchRole()`](#method-matchRole) protected |  | `AccessRule` |
| [`matchVerb()`](#method-matchVerb) protected |  | `AccessRule` |

## Property details

### $actions <span id="property-actions"></span>

```php
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 <span id="property-controllers"></span>

```php
public array|null $controllers = null
```

List of the controller IDs that this rule applies to.

The comparison uses [`Controller::$uniqueId`](/docs/api/yii/base/controller/index.md#property-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 <span id="property-denyCallback"></span>

```php
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`](/docs/api/yii/filters/accessrule/index.md#property-allow) is set to `false`.

If not set, the behavior will be determined by [`AccessControl`](/docs/api/yii/filters/accesscontrol/index.md),
either using [`AccessControl::denyAccess()`](/docs/api/yii/filters/accesscontrol/index.md#method-denyAccess)
or [`AccessControl::$denyCallback`](/docs/api/yii/filters/accesscontrol/index.md#property-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](/docs/api/yii/base/action/index.md) object.

### $ips <span id="property-ips"></span>

```php
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 <span id="property-matchCallback"></span>

```php
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](/docs/api/yii/base/action/index.md) object.
The callback should return a boolean value indicating whether this rule should be applied.

### $permissions <span id="property-permissions"></span>

```php
public array|null $permissions = null
```

List of RBAC (Role-Based Access Control) permissions that this rules applies to. [`User::can()`](/docs/api/yii/web/user/index.md#method-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 <span id="property-roleParams"></span>

```php
public array|object|Closure $roleParams = []
```

Parameters to pass to the [`User::can()`](/docs/api/yii/web/user/index.md#method-can) function for evaluating user permissions in [`$roles`](/docs/api/yii/filters/accessrule/index.md#property-roles).

If this is an array, it will be passed directly to [`User::can()`](/docs/api/yii/web/user/index.md#method-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`](/docs/api/yii/filters/accessrule/index.md) instance will be passed to the closure as the first parameter.

**Since**

2.0.12

### $roles <span id="property-roles"></span>

```php
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`](/docs/api/yii/web/user/index.md#property-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()`](/docs/api/yii/web/user/index.md#method-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 <span id="property-verbs"></span>

```php
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() <span id="method-allows"></span>

```php
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`](/docs/api/yii/base/action/index.md) | The action to be performed |
| `$user` | [`yii\web\User`](/docs/api/yii/web/user/index.md)`\|false` | The user object or `false` in case of detached User component |
| `$request` | [`yii\web\Request`](/docs/api/yii/web/request/index.md) |  |

**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() <span id="method-matchAction"></span>

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

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$action` | [`yii\base\Action`](/docs/api/yii/base/action/index.md) | The action |

**Returns**

`bool`: Whether the rule applies to the action

### matchController() <span id="method-matchController"></span>

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

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$controller` | [`yii\base\Controller`](/docs/api/yii/base/controller/index.md)`\|null` | The controller, or `null` when the action runs as a standalone action dispatched by [`Module::$actionMap`](/docs/api/yii/base/module/index.md#property-actionMap) (since 22.0). |

**Returns**

`bool`: Whether the rule applies to the controller.

### matchCustom() <span id="method-matchCustom"></span>

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

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$action` | [`yii\base\Action`](/docs/api/yii/base/action/index.md) | The action to be performed |

**Returns**

`bool`: Whether the rule should be applied

### matchIP() <span id="method-matchIP"></span>

```php
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() <span id="method-matchRole"></span>

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

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$user` | [`yii\web\User`](/docs/api/yii/web/user/index.md) | The user object |

**Returns**

`bool`: Whether the rule applies to the role

**Throws**

- [`yii\base\InvalidConfigException`](/docs/api/yii/base/invalidconfigexception/index.md): if User component is detached

### matchVerb() <span id="method-matchVerb"></span>

```php
protected function matchVerb(string $verb): bool
```

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$verb` | `string` | The request method. |

**Returns**

`bool`: Whether the rule applies to the request