# RateLimiter

> RateLimiter implements a rate limiting algorithm based on the [leaky bucket algorithm](https://en.wikipedia.org/wiki/Leaky_bucket).

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

| class | `yii\filters\RateLimiter` |
| --- | --- |
| Extends | [`yii\base\ActionFilter`](/docs/api/yii/base/actionfilter/index.md) » [`yii\base\Behavior`](/docs/api/yii/base/behavior/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/RateLimiter.php`](https://github.com/yiisoft/yii2/blob/22.0/framework/filters/RateLimiter.php#L50) |

RateLimiter implements a rate limiting algorithm based on the [leaky bucket algorithm](https://en.wikipedia.org/wiki/Leaky_bucket).

You may use RateLimiter by attaching it as a behavior to a controller or module, like the following,

```
public function behaviors()
{
    return [
        'rateLimiter' => [
            'class' => \yii\filters\RateLimiter::class,
        ],
    ];
}
```

When the user has exceeded his rate limit, RateLimiter will throw a [`TooManyRequestsHttpException`](/docs/api/yii/web/toomanyrequestshttpexception/index.md) exception.

Note that RateLimiter requires [`$user`](/docs/api/yii/filters/ratelimiter/index.md#property-user) to implement the [`RateLimitInterface`](/docs/api/yii/filters/ratelimitinterface/index.md). RateLimiter will
do nothing if [`$user`](/docs/api/yii/filters/ratelimiter/index.md#property-user) is not set or does not implement [`RateLimitInterface`](/docs/api/yii/filters/ratelimitinterface/index.md).

## Properties

| Property | Type | Description | Defined by |
| --- | --- | --- | --- |
| <span id="property-enableRateLimitHeaders"></span>`$enableRateLimitHeaders` | `bool` | Whether to include rate limit headers in the response Default: `true`. | `RateLimiter` |
| <span id="property-errorMessage"></span>`$errorMessage` | `string` | The message to be displayed when rate limit exceeds Default: `'Rate limit exceeded.'`. | `RateLimiter` |
| <span id="property-except"></span>[`$except`](/docs/api/yii/base/actionfilter/index.md#property-except) | `array` | List of action IDs that this filter should not apply to. Default: `[]`. | [`yii\base\ActionFilter`](/docs/api/yii/base/actionfilter/index.md) |
| <span id="property-only"></span>[`$only`](/docs/api/yii/base/actionfilter/index.md#property-only) | `array` | List of action IDs that this filter should apply to. Default: `[]`. | [`yii\base\ActionFilter`](/docs/api/yii/base/actionfilter/index.md) |
| <span id="property-owner"></span>[`$owner`](/docs/api/yii/base/behavior/index.md#property-owner) | `yii\base\T\|null` | The owner of this behavior Default: `null`. | [`yii\base\Behavior`](/docs/api/yii/base/behavior/index.md) |
| [`$request`](#property-request) | [`yii\web\Request`](/docs/api/yii/web/request/index.md)`\|null` | The current request. Default: `null`. | `RateLimiter` |
| [`$response`](#property-response) | [`yii\web\Response`](/docs/api/yii/web/response/index.md)`\|null` | The response to be sent. Default: `null`. | `RateLimiter` |
| [`$user`](#property-user) | [`RateLimitInterface`](/docs/api/yii/filters/ratelimitinterface/index.md)`\|`[`yii\web\IdentityInterface`](/docs/api/yii/web/identityinterface/index.md)`\|`[`Closure`](https://www.php.net/manual/en/class.closure.php)`\|null` | The user object that implements the RateLimitInterface. Default: `null`. | `RateLimiter` |

## 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/baseobject/index.md#method-__call) | Calls the named method which is not a class method. | [`yii\base\BaseObject`](/docs/api/yii/base/baseobject/index.md) |
| <span id="method-__get"></span>[`__get()`](/docs/api/yii/base/baseobject/index.md#method-__get) | Returns the value of an object property. | [`yii\base\BaseObject`](/docs/api/yii/base/baseobject/index.md) |
| <span id="method-__isset"></span>[`__isset()`](/docs/api/yii/base/baseobject/index.md#method-__isset) | Checks if a property is set, i.e. defined and not null. | [`yii\base\BaseObject`](/docs/api/yii/base/baseobject/index.md) |
| <span id="method-__set"></span>[`__set()`](/docs/api/yii/base/baseobject/index.md#method-__set) | Sets value of an object property. | [`yii\base\BaseObject`](/docs/api/yii/base/baseobject/index.md) |
| <span id="method-__unset"></span>[`__unset()`](/docs/api/yii/base/baseobject/index.md#method-__unset) | Sets an object property to null. | [`yii\base\BaseObject`](/docs/api/yii/base/baseobject/index.md) |
| [`addRateLimitHeaders()`](#method-addRateLimitHeaders) | Adds the rate limit headers to the response. | `RateLimiter` |
| <span id="method-afterAction"></span>[`afterAction()`](/docs/api/yii/base/actionfilter/index.md#method-afterAction) | This method is invoked right after an action is executed. | [`yii\base\ActionFilter`](/docs/api/yii/base/actionfilter/index.md) |
| <span id="method-afterFilter"></span>[`afterFilter()`](/docs/api/yii/base/actionfilter/index.md#method-afterFilter) |  | [`yii\base\ActionFilter`](/docs/api/yii/base/actionfilter/index.md) |
| <span id="method-attach"></span>[`attach()`](/docs/api/yii/base/actionfilter/index.md#method-attach) | Attaches the behavior object to the component. | [`yii\base\ActionFilter`](/docs/api/yii/base/actionfilter/index.md) |
| [`beforeAction()`](#method-beforeAction) | This method is invoked right before an action is to be executed (after all possible filters.) You may override this method to do last-minute preparation for the action. | `RateLimiter` |
| <span id="method-beforeFilter"></span>[`beforeFilter()`](/docs/api/yii/base/actionfilter/index.md#method-beforeFilter) |  | [`yii\base\ActionFilter`](/docs/api/yii/base/actionfilter/index.md) |
| <span id="method-canGetProperty"></span>[`canGetProperty()`](/docs/api/yii/base/baseobject/index.md#method-canGetProperty) | Returns a value indicating whether a property can be read. | [`yii\base\BaseObject`](/docs/api/yii/base/baseobject/index.md) |
| <span id="method-canSetProperty"></span>[`canSetProperty()`](/docs/api/yii/base/baseobject/index.md#method-canSetProperty) | Returns a value indicating whether a property can be set. | [`yii\base\BaseObject`](/docs/api/yii/base/baseobject/index.md) |
| [`checkRateLimit()`](#method-checkRateLimit) | Checks whether the rate limit exceeds. | `RateLimiter` |
| <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-detach"></span>[`detach()`](/docs/api/yii/base/actionfilter/index.md#method-detach) | Detaches the behavior object from the component. | [`yii\base\ActionFilter`](/docs/api/yii/base/actionfilter/index.md) |
| <span id="method-events"></span>[`events()`](/docs/api/yii/base/behavior/index.md#method-events) | Declares event handlers for the [`$owner`](/docs/api/yii/base/behavior/index.md#property-owner)'s events. | [`yii\base\Behavior`](/docs/api/yii/base/behavior/index.md) |
| <span id="method-hasMethod"></span>[`hasMethod()`](/docs/api/yii/base/baseobject/index.md#method-hasMethod) | Returns a value indicating whether a method is defined. | [`yii\base\BaseObject`](/docs/api/yii/base/baseobject/index.md) |
| <span id="method-hasProperty"></span>[`hasProperty()`](/docs/api/yii/base/baseobject/index.md#method-hasProperty) | Returns a value indicating whether a property is defined. | [`yii\base\BaseObject`](/docs/api/yii/base/baseobject/index.md) |
| [`init()`](#method-init) | Initializes the object. | `RateLimiter` |
| <span id="method-getActionId"></span>[`getActionId()`](/docs/api/yii/base/actionfilter/index.md#method-getActionId) protected | Returns an action ID by converting [`Action::$uniqueId`](/docs/api/yii/base/action/index.md#property-uniqueId) into an ID relative to the module. | [`yii\base\ActionFilter`](/docs/api/yii/base/actionfilter/index.md) |
| <span id="method-isActive"></span>[`isActive()`](/docs/api/yii/base/actionfilter/index.md#method-isActive) protected | Returns a value indicating whether the filter is active for the given action. | [`yii\base\ActionFilter`](/docs/api/yii/base/actionfilter/index.md) |

## Property details

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

```php
public yii\web\Request|null $request = null
```

The current request.

If not set, the `request` application component will be used.

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

```php
public yii\web\Response|null $response = null
```

The response to be sent.

If not set, the `response` application component will be used.

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

```php
public yii\filters\RateLimitInterface|yii\web\IdentityInterface|Closure|null $user = null
```

The user object that implements the RateLimitInterface.

If not set, it will take the value of `Yii::$app->user->getIdentity(false)`.
{@since 2.0.38} It's possible to provide a closure function in order to assign the user identity on runtime. Using a closure to assign the user identity is recommend
when you are **not** using the standard `Yii::$app->user` component. See the example below:
```
'user' => function() {
    return Yii::$app->apiUser->identity;
}
```

## Method details

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

```php
public function addRateLimitHeaders(yii\web\Response $response, int $limit, int $remaining, int $reset): mixed
```

Adds the rate limit headers to the response.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$response` | [`yii\web\Response`](/docs/api/yii/web/response/index.md) |  |
| `$limit` | `int` | The maximum number of allowed requests during a period |
| `$remaining` | `int` | The remaining number of allowed requests within the current period |
| `$reset` | `int` | The number of seconds to wait before having maximum number of allowed requests again |

**Returns**

`mixed`

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

```php
public function beforeAction(mixed $action): bool
```

This method is invoked right before an action is to be executed (after all possible filters.)
You may override this method to do last-minute preparation for the action.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$action` | `mixed` | The action to be executed. |

**Returns**

`bool`: Whether the action should continue to be executed.

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

```php
public function checkRateLimit(yii\filters\RateLimitInterface $user, yii\web\Request $request, yii\web\Response $response, yii\base\Action $action): mixed
```

Checks whether the rate limit exceeds.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$user` | [`RateLimitInterface`](/docs/api/yii/filters/ratelimitinterface/index.md) | The current user |
| `$request` | [`yii\web\Request`](/docs/api/yii/web/request/index.md) |  |
| `$response` | [`yii\web\Response`](/docs/api/yii/web/response/index.md) |  |
| `$action` | [`yii\base\Action`](/docs/api/yii/base/action/index.md) | The action to be executed |

**Returns**

`mixed`

**Throws**

- [`yii\web\TooManyRequestsHttpException`](/docs/api/yii/web/toomanyrequestshttpexception/index.md): if rate limit exceeds

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

```php
public function init(): mixed
```

Initializes the object.

This method is invoked at the end of the constructor after the object is initialized with the
given configuration.

**Returns**

`mixed`