Download the PHP package thamtech/yii2-ratelimiter-advanced without Composer
On this page you can find all versions of the php package thamtech/yii2-ratelimiter-advanced. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download thamtech/yii2-ratelimiter-advanced
More information about thamtech/yii2-ratelimiter-advanced
Files in thamtech/yii2-ratelimiter-advanced
Package yii2-ratelimiter-advanced
Short Description An advanced request rate limiter
License BSD-3-Clause
Informations about the package yii2-ratelimiter-advanced
Yii2 Advanced Rate Limiter
Advanced Rate Limiter is a Yii2's filter to enforce or monitor request rate limits.
In contrast to Yii2's built-in RateLimiter, Advanced Rate Limiter:
- allows you to define multiple, independent rate limit definitions
- by controller action, and
- by an identifier such as an IP address, user ID, other identifiers relevant to your application, or a combination thereof;
- provides support for customizing the type of response to a checked or
exceeded rate limit such as:
- sending a
429 Too Many Requests
HTTP response, - triggering a Yii2 Event,
- setting rate-limit HTTP headers, and/or
- executing your own Callable or anonymous function;
- sending a
- provides support for storing and managing the
allowance
andtimestamp
values for each rate limit (Yii2's built-in RateLimiter requires you to implement the storage yourself); - allows you to customize the prefix of rate-limit HTTP headers instead of the
hardcoded
X-Rate-Limit-
prefix used by the built-inRateLimiter
; - provides support for sending the
Retry-After
HTTP header indicating how many seconds the client should wait before retrying.
For license information check the LICENSE-file.
Installation
The preferred way to install this extension is through composer.
or add
to the require
section of your composer.json
file.
Usage
Introduction
This Rate Limiter is an implementation of the leaky bucket algorithm.
In general, you will configure the rate limiter as a behavior on any Controller class you want to rate limit. For example,
Advanced Example:
Storage
In order to assign one or more rate limits, you must be able to store
an integer allowance
value and a timestamp
for each configured
rate limit.
Default Allowance Storage in Cache
The RateLimiter uses an allowanceStorage
component for storing the rate
limit values. By default, the AllowanceCacheStorage
component stores the
allowance data in the cache component you specify. If no cache
is specified, an instance of yii\caching\DummyCache
will be used.
You can specify a cache component in several ways:
Implement Your Own Storage Layer
However, you may use your own storage layer implementation by implementing
AllowanceStorageInterface
and referencing your implementation in
RateLimiter
's allowanceStorage
component.
For example:
Defining Rate Limits
A single RateLimiter
can have one or more separate rate limits defined. For example,
you may wish to provide one rate limit for each IP address and a different rate limit for
each authenticated user, especially when this is not always a one-to-one mapping.
A simple rate limit can be defined like the following:
By returning an identifier
value, you can enforce the defined rate limit on
a per-identifier basis, such as per IP address. Or you may leave the identifier
unspecified in order to apply the defined rate limit globally.
You can also implement your own rate limit definition by referencing
an implementation of the RateLimitInterface
:
You will need to implement the getRateLimit($context)
method to return
a RateLimit
object or an array of its properties (limit
, window
, and optionally
an identifier
such as a user ID, and optionally an active
boolean).
Defining Responses
There can be any number of responses to an exceeded rate limit. A couple of predefined
response types can be attached as behaviors of the RateLimiter
. For example:
A more advanced example with some additional configuration options set:
You may also attach your own event handlers to the RateLimiter
object to look
for RateLimiter::EVENT_RATE_LIMITS_EXCEEDED
or RateLimiter::EVENT_RATE_LIMITS_CHECKED
events:
Alternatively, you can attach event handlers using the on()
method:
See Yii's Events page for more information about attaching Event handlers.
Filtering Events
If the only
and except
properties of the handlers are not enough for filtering,
your custom event handler can set $event->handled
to true to prevent any other handler
from being invoked.
For example, if you want to whitelist an IP address:
Events
RateLimitsCheckedEvent
The RateLimitsCheckedEvent
is triggered whenever a set of defined rate limits
are checked. The RateLimitsExceededEvent
is triggered whenever one or more of the defined
rate limits are exceeded. The predefined responses attached to the RateLimiter
as
behaviors all work by registering themselves as event handlers and looking for
these events.
Both events include the following properties:
$context
- the Context object containing theyii\web\Request
and$action
$time
- the current unix timestamp$rateLimits
- an array ofRateLimitResult
objects. Only those rate limits that were exceeded are included in theRateLimitsExceededEvent
.
Predefined responses such as the RateLimitHeadersHandler
will make use of the
rate information in order to output the appropriate values in the HTTP headers.
In the case of RateLimitHeadersHandler
, the information from multiple rate
limits may be combined together in order to compute one set of HTTP header values.
Other responses, such as the TooManyRequestsHttpExceptionHandler
, will not care
what or how many rate limits were exceeded. It will just throw the
TooManyRequestsHttpException
no matter what.
Some responses are triggered whenever rate limits are checked, such as the
RateLimitHeadersHandler
which will add its HTTP headers to every response
to indicate to the client how it is doing with respect to its rate limits.
Other responses, such as the TooManyRequestsHttpExceptionHandler
will
only apply when rate limits are exceeded.
Order of Responses
The order in which responses are added matters.
Response handlers are executed in the order in which they are attached to the
RateLimiter
. This means that an exception-throwing handler, like
TooManyRequestsHttpException
, must come after header-setting handlers, like
RateLimitHeadersHandler
.
Recipes
See Recipes