yiisoft / rate-limiter
Yii Rate Limiter Middleware
Fund package maintenance!
Open Collective
yiisoft
Installs: 9 587
Dependents: 2
Suggesters: 0
Security: 0
Stars: 18
Watchers: 15
Forks: 8
Open Issues: 6
Requires
- php: ^7.4|^8.0
- psr/http-factory: ^1.0
- psr/http-message: ^1.0
- psr/http-message-implementation: 1.0
- psr/http-server-handler: ^1.0
- psr/http-server-middleware: ^1.0
- psr/simple-cache: ^1.0
- yiisoft/http: ^1.0
Requires (Dev)
- nyholm/psr7: ^1.0
- phpunit/phpunit: ^9.4
- roave/infection-static-analysis-plugin: ^1.5
- spatie/phpunit-watcher: ^1.23
- vimeo/psalm: ^4.2
- yiisoft/cache: ^1.0
Provides
This package is auto-updated.
Last update: 2023-05-28 06:05:35 UTC
README
Yii Rate Limiter Middleware
Rate limiter middleware helps to prevent abuse by limiting the number of requests that could be me made consequentially.
For example, you may want to limit the API usage of each user to be at most 100 API calls within a period of 10 minutes. If too many requests are received from a user within the stated period of the time, a response with status code 429 (meaning "Too Many Requests") should be returned.
Requirements
- PHP 7.4 or higher.
Installation
The package could be installed with composer:
composer install yiisoft/rate-limiter --prefer-dist
General usage
use Psr\Http\Message\ServerRequestInterface; use Yiisoft\Yii\RateLimiter\LimitRequestsMiddleware; use Yiisoft\Yii\RateLimiter\Counter; use Nyholm\Psr7\Factory\Psr17Factory; use Yiisoft\Yii\RateLimiter\Policy\LimitAlways; use Yiisoft\Yii\RateLimiter\Policy\LimitPerIp; use Yiisoft\Yii\RateLimiter\Policy\LimitCallback; use Yiisoft\Yii\RateLimiter\Storage\StorageInterface; use Yiisoft\Yii\RateLimiter\Storage\SimpleCacheStorage; /** @var StorageInterface $storage */ $storage = new SimpleCacheStorage($cache); $counter = new Counter($storage, 2, 5); $responseFactory = new Psr17Factory(); $middleware = new LimitRequestsMiddleware($counter, $responseFactory); // LimitPerIp by default
In the above 2 is the maximum number of counter increments (requests) that could be performed before increments are limited and 5 is a period to apply limit to, in seconds.
The Counter
implements generic cell rate limit algorithm (GCRA)
that ensures that after reaching the limit further increments are distributed equally.
Note: While it is sufficiently effective, it is preferred to use Nginx or another webserver capabilities for rate limiting. This package allows rate-limiting in the project with deployment environment you cannot control such as installable CMS.
Implementing your own limiting policy
There are two ready to use limiting policies available in the package:
LimitAlways
- to count all incoming requests.LimitPerIp
- to count requests from different IPs separately.
These could be applied as follows:
$middleware = new LimitRequestsMiddleware($counter, $responseFactory, new LimitPerIp()); // or $middleware = new LimitRequestsMiddleware($counter, $responseFactory, new LimitAlways());
Easiest way to customize a policy is to use LimitCallback
:
$middleware = new LimitRequestsMiddleware($counter, $responseFactory, new LimitCallback(function (ServerRequestInterface $request): string { // return user id from database if authentication id used i.e. limit guests and each authenticated user separately. }));
Another way it to implement Yiisoft\Yii\RateLimiter\Policy\LimitPolicyInterface
and use it in a similar way as above.
Implementing your own counter storage
By default, the package provides \Yiisoft\Yii\RateLimiter\Storage\SimpleCacheStorage
that stores counters
in any PSR-16 cache. To have your own storage
implement Yiisoft\Yii\RateLimiter\Storage\StorageInterface
.
Testing
Unit testing
The package is tested with PHPUnit. To run tests:
./vendor/bin/phpunit
Mutation testing
The package tests are checked with Infection mutation framework with Infection Static Analysis Plugin. To run it:
./vendor/bin/roave-infection-static-analysis-plugin
Static analysis
The code is statically analyzed with Psalm. To run static analysis:
./vendor/bin/psalm
License
The Yii Rate Limiter Middleware is free software. It is released under the terms of the BSD License.
Please see LICENSE
for more information.
Maintained by Yii Software.