fyre/ratelimiter

A rate limiter library.

v4.0.2 2024-11-11 10:04 UTC

Requires

• fyre/cache: ^5.0
• fyre/container: ^1.0
• fyre/middleware: ^5.0
• fyre/server: ^3.0

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.59
• fyre/php-cs-fixer-config: ^1.0
• phpunit/phpunit: ^11

MIT

• elusivecodes

README

FyreRateLimiter is a free, open-source rate limiting library for PHP.

Table Of Contents

• Installation
• Basic Usage
• Methods
• Middleware

Installation

Using Composer

composer require fyre/ratelimiter

In PHP:

use Fyre\Security\RateLimiter;

Basic Usage

• $container is a Container.
• $cacheManager is a CacheManager.
• $options is an array containing options for the RateLimiter.
  • cacheConfig is a string representing the configuration key for the Cache, and will default to "ratelimiter".
  • limit is a number representing the maximum number of requests that can be made within the period, and will default to 60.
  • period is a number representing the number of seconds per rate limiting period, and will default to 60.
  • message is a string representing the rate limit error message, and will default to "Rate limit exceeded".
  • headers is an array containing the rate limit headers.
    • limit is a string representing the rate limit header, and will default to "X-RateLimit-Limit".
    • remaining is a string representing the rate limit remaining header, and will default to "X-RateLimit-Remaining".
    • reset is a string representing the rate limit reset header, and will default to "X-RateLimit-Reset".
  • identifier is a Closure that accepts a ServerRequest as the first argument, and should return a string representing the client identifier.
  • skipCheck is a Closure that accepts a ServerRequest as the first argument, and can return true to skip rate limit checks for the request.
  • errorResponse is a Closure that accepts a ServerRequest and a ClientResponse as the arguments, and should return a ClientResponse.

$limiter = new RateLimiter($container, $cacheManager, $options);

If the cacheConfig doesn't exist in the CacheManager, a default FileCacher will be created instead.

If the identifier callback is omitted, it will default to using the $_SERVER['REMOTE_ADDR'].

If the errorResponse callback is omitted, it will default to negotiating a json or plaintext response containing the message option.

Autoloading

Any dependencies will be injected automatically when loading from the Container.

$limiter = $container->use(RateLimiter::class, ['options' => $options]);

Methods

Add Headers

Add rate limit headers to a ClientResponse.

• $response is a ClientResponse.

$response = $limiter->addHeaders($response);

Check Limit

Determine whether the rate limit has been reached for a request.

• $request is the ServerRequest.

$result = $limiter->checkLimit($request);

Error Response

Generate an error response.

• $request is the ServerRequest.

$response = $limiter->errorResponse($request);

Middleware

use Fyre\Security\Middleware\RateLimiterMiddleware;

• $container is a Container.
• $options is an array containing options for the RateLimiter.
  • cacheConfig is a string representing the configuration key for the Cache, and will default to "ratelimiter".
  • limit is a number representing the maximum number of requests that can be made within the period, and will default to 60.
  • period is a number representing the number of seconds per rate limiting period, and will default to 60.
  • message is a string representing the rate limit error message, and will default to "Rate limit exceeded".
  • headers is an array containing the rate limit headers.
    • limit is a string representing the rate limit header, and will default to "X-RateLimit-Limit".
    • remaining is a string representing the rate limit remaining header, and will default to "X-RateLimit-Remaining".
    • reset is a string representing the rate limit reset header, and will default to "X-RateLimit-Reset".
  • identifier is a Closure that accepts a ServerRequest as the first argument, and should return a string representing the client identifier.
  • skipCheck is a Closure that accepts a ServerRequest as the first argument, and can return true to skip rate limit checks for the request.
  • errorResponse is a Closure that accepts a ServerRequest and a ClientResponse as the arguments, and should return a ClientResponse.

$middleware = new RateLimiterMiddleware($container, $options);

Any dependencies will be injected automatically when loading from the Container.

$middleware = $container->build(RateLimiterMiddleware::class, ['options' => $options]);

Handle

Handle a ServerRequest.

• $request is a ServerRequest.
• $next is a Closure.

$response = $middleware->handle($request, $next);

This method will return a ClientResponse.