PHP Ratelimiter
A framework independent, flexible and highly extensible rate limiter for PHP., (*1)
, (*2)
Installation
With Composer
It is best installed it through packagist
by including sunspikes/php-ratelimiter in your project composer.json require:, (*3)
``` json
"require": {
"sunspikes/php-ratelimiter": "dev-master"
}, (*4)
### Without Composer
You can also download it from [Github](https://github.com/sunspikes/php-ratelimiter),
but no autoloader is provided so you'll need to register it with your own PSR-4
compatible autoloader.
## Usage
### Overview
```php
// 1. Make a rate limiter with limit 3 attempts in 10 minutes
$cacheAdapter = new DesarrollaCacheAdapter((new DesarrollaCacheFactory())->make());
$settings = new ElasticWindowSettings(3, 600);
$ratelimiter = new RateLimiter(new ThrottlerFactory($cacheAdapter), new HydratorFactory(), $settings);
// 2. Get a throttler for path /login
$loginThrottler = $ratelimiter->get('/login');
// 3. Register a hit
$loginThrottler->hit()
// 4. Check if it reached the limit
if ($loginThrottler->check()) {
// access permitted
} else {
// access denied
}
// Or combine the steps 3 & 4
if ($loginThrottler->access()) {
// access permitted
} else {
// access denied
}
// To get the number of hits
print $loginThrottler->count(); // or count($throttler)
Configuration
By default PHP Ratelimiter uses the desarolla2 cache adapter, the sample configuration provided in config/config.php, (*5)
You can configure the drivers in config.php, for example to use memcache change the driver to 'memcache', (*6)
return [
'default_ttl' => 3600,
'driver' => 'memcache',
'memcache' => [
//....
],
];
Extending
The PHP Ratelimiter is highly extensible, you can have custom adapters by implementing Sunspikes\Ratelimit\Cache\Adapter\CacheAdapterInterface, (*7)
For example to use Doctrine cache adapter, (*8)
class DoctrineCacheAdapter implements CacheAdapterInterface
{
public function __construct($cache)
{
$this->cache = $cache;
}
// Implement the methods
}
// Build adapter using APC cache driver
$adapter = new DoctrineCacheAdapter(new \Doctrine\Common\Cache\ApcCache());
Also you can have custom hydrators by implementing Sunspikes\Ratelimit\Throttle\Hydrator\DataHydratorInterface, (*9)
For example to use a Symfony Request object instead of custom URL for ratelimiting, (*10)
class RequestHydrator implements DataHydratorInterface
{
public function hydrate($data, $limit, $ttl)
{
// Make the key string
$key = $data->getClientIp() . $data->getPathInfo();
return new Data($key, $limit, $ttl);
}
}
// Hydrate the request to Data object
$hydrator = new RequestHydrator();
Then decorate or extend the HydratorFactory to recognize your data, (*11)
use Hydrator\FactoryInterface;
class MyHydratorFactory implements FactoryInterface
{
private $defaultFactory;
public function __construct(FactoryInterface $defaultFactory)
{
$this->defaultFactory = $defaultFactory;
}
public function make($data)
{
if ($data instanceof Request) {
return new RequestHydrator();
}
return $this->defaultFactory->make($data);
}
}
Throttler types
Elastic Window
An elastic window throttler will allow X requests in Y seconds. Any further access attempts will be counted, but return false as status. Note that the window will be extended with Y seconds on every hit. This means there need to be no hits during Y seconds for the counter to be reset to 0., (*12)
See Overview example for instantiation., (*13)
Time-based throttlers
All the following throttlers use time functions, thus needing a different factory for construction:, (*14)
$cacheAdapter = new DesarrollaCacheAdapter((new DesarrollaCacheFactory())->make());
$timeAdapter = new PhpTimeAdapter();
$throttlerFactory = new TimeAwareThrottlerFactory($cacheAdapter, $timeAdapter);
$hydratorFactory = new HydratorFactory();
//$settings = ...
$ratelimiter = new RateLimiter($throttlerFactory, $hydratorFactory, $settings);
Fixed Window
A fixed window throttler will allow X requests in the Y seconds since the first request. Any further access attempts will be counted, but return false as status. The window will not be extended at all., (*15)
// Make a rate limiter with limit 120 attempts per minute
$settings = new FixedWindowSettings(120, 60);
Moving Window
A moving window throttler will allow X requests during the previous Y seconds. Any further access attempts will be counted, but return false as status. The window is never extended beyond Y seconds., (*16)
// Make a rate limiter with limit 120 attempts per minute
$settings = new MovingWindowSettings(120, 60);
Leaky Bucket
A leaky bucket throttler will allow X requests divided over time Y., (*17)
Any access attempts past the threshold T (default: 0) will be delayed by Y / (X - T), (*18)
access() will return false if delayed, hit() will return the number of milliseconds waited, (*19)
Note: Time limit for this throttler is in milliseconds, where it is seconds for the other throttler types!, (*20)
// Make a rate limiter with limit 120 attempts per minute, start delaying after 30 requests
$settings = new LeakyBucketSettings(120, 60000, 30);
Retrial Queue
The retrial queue encapsulates another throttler.
When this throttler receives a hit which would fail on the internal throttler,
the request is delayed until the internal throttler has capacity again., (*21)
// Make a leaky bucket ratelimiter which delays any overflow
$settings = new RetrialQueueSettings(new LeakyBucketSettings(120, 60000, 120));
Author
Krishnaprasad MG [@sunspikes], (*22)
Contributing
Please feel free to send pull requests., (*23)
License
This is an open-sourced software licensed under the MIT license., (*24)
Wallogit.com
