RateLimiter

API reference › yii › filters › RateLimiter

class	`yii\filters\RateLimiter`
Extends	`yii\base\ActionFilter` » `yii\base\Behavior` » `yii\base\BaseObject`
Implements	`yii\base\Configurable`
Since	2.0
Source	`framework/filters/RateLimiter.php`

RateLimiter implements a rate limiting algorithm based on the leaky bucket algorithm.

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 exception.

Note that RateLimiter requires $user to implement the RateLimitInterface. RateLimiter will do nothing if $user is not set or does not implement RateLimitInterface.

Properties

Property	Type	Description	Defined by
`$enableRateLimitHeaders`	`bool`	Whether to include rate limit headers in the response Default: `true`.	`RateLimiter`
`$errorMessage`	`string`	The message to be displayed when rate limit exceeds Default: `'Rate limit exceeded.'`.	`RateLimiter`
`$except`	`array`	List of action IDs that this filter should not apply to. Default: `[]`.	`yii\base\ActionFilter`
`$only`	`array`	List of action IDs that this filter should apply to. Default: `[]`.	`yii\base\ActionFilter`
`$owner`	`yii\base\T\|null`	The owner of this behavior Default: `null`.	`yii\base\Behavior`
`$request`	`yii\web\Request\|null`	The current request. Default: `null`.	`RateLimiter`
`$response`	`yii\web\Response\|null`	The response to be sent. Default: `null`.	`RateLimiter`
`$user`	`RateLimitInterface\|yii\web\IdentityInterface\|Closure\|null`	The user object that implements the RateLimitInterface. Default: `null`.	`RateLimiter`

Methods

Method	Description	Defined by
`__construct()`	Constructor.	`yii\base\BaseObject`
`__call()`	Calls the named method which is not a class method.	`yii\base\BaseObject`
`__get()`	Returns the value of an object property.	`yii\base\BaseObject`
`__isset()`	Checks if a property is set, i.e. defined and not null.	`yii\base\BaseObject`
`__set()`	Sets value of an object property.	`yii\base\BaseObject`
`__unset()`	Sets an object property to null.	`yii\base\BaseObject`
`addRateLimitHeaders()`	Adds the rate limit headers to the response.	`RateLimiter`
`afterAction()`	This method is invoked right after an action is executed.	`yii\base\ActionFilter`
`afterFilter()`		`yii\base\ActionFilter`
`attach()`	Attaches the behavior object to the component.	`yii\base\ActionFilter`
`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`
`beforeFilter()`		`yii\base\ActionFilter`
`canGetProperty()`	Returns a value indicating whether a property can be read.	`yii\base\BaseObject`
`canSetProperty()`	Returns a value indicating whether a property can be set.	`yii\base\BaseObject`
`checkRateLimit()`	Checks whether the rate limit exceeds.	`RateLimiter`
`className()` static	Returns the fully qualified name of this class.	`yii\base\BaseObject`
`detach()`	Detaches the behavior object from the component.	`yii\base\ActionFilter`
`events()`	Declares event handlers for the `$owner`’s events.	`yii\base\Behavior`
`hasMethod()`	Returns a value indicating whether a method is defined.	`yii\base\BaseObject`
`hasProperty()`	Returns a value indicating whether a property is defined.	`yii\base\BaseObject`
`init()`	Initializes the object.	`RateLimiter`
`getActionId()` protected	Returns an action ID by converting `Action::$uniqueId` into an ID relative to the module.	`yii\base\ActionFilter`
`isActive()` protected	Returns a value indicating whether the filter is active for the given action.	`yii\base\ActionFilter`

Property details

$request

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

The current request.

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

$response

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

The response to be sent.

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

$user

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()

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`
`$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()

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()

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`	The current user
`$request`	`yii\web\Request`
`$response`	`yii\web\Response`
`$action`	`yii\base\Action`	The action to be executed

Returns

mixed

Throws

yii\web\TooManyRequestsHttpException: if rate limit exceeds

init()

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