Skip to content
This repository has been archived by the owner on Feb 13, 2024. It is now read-only.

Implementation of the Token Bucket algorithm in PHP.

License

Notifications You must be signed in to change notification settings

Webador/token-bucket

 
 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Caution

This project is archived. Please implement the more recent symfony/rate-limiter. It also implements the token bucket algorithm and enjoys better support.

Token Bucket

This is a fork of bandwidth-throttle/token-bucket originally created to add support for zend-cache (now laminas-cache).

This is a threadsafe implementation of the Token Bucket algorithm in PHP. You can use a token bucket to limit an usage rate for a resource. (E.g., a stream bandwidth or an API usage.)

The token bucket is an abstract metaphor and can be applied in throttling both consumption and production of resources. E.g., you can limit the consumption rate of a third party API, or you can limit the rate at which others can use yours.

Installation

Use Composer:

composer require jouwweb/token-bucket

Example

This example will limit the rate of a global resource to 10 requests per second for all requests.

use JouwWeb\TokenBucket\Rate;
use JouwWeb\TokenBucket\TokenBucket;
use JouwWeb\TokenBucket\storage\FileStorage;

$storage = new FileStorage(__DIR__ . "/api.bucket");
$rate = new Rate(10, Rate::SECOND);
$bucket = new TokenBucket(10, $rate, $storage);
$bucket->bootstrap(10);

if (!$bucket->consume(1, $seconds)) {
    http_response_code(429);
    header(sprintf("Retry-After: %d", floor($seconds)));
    exit();
}

echo "API response";

Note: In this example TokenBucket::bootstrap() is part of the code. This is not recommended for production, as this is producing unnecessary storage communication. TokenBucket::bootstrap() should be part of the application's bootstrap or deploy process to provide an intial amount of available tokens.

BlockingConsumer

In the example we either served the request or failed with the HTTP status 429. This is a very resource efficient way of throttling requests, but sometimes it is desirable to not fail but instead wait untill the request can pass. You can achieve this by consuming the token bucket with an instance of BlockingConsumer:

use JouwWeb\TokenBucket\BlockingConsumer;
/** @var \JouwWeb\TokenBucket\TokenBucket $bucket */

$consumer = new BlockingConsumer($bucket);

// This will block until one token is available.
$consumer->consume(1);

echo "API response";

Adding this to the previous example will effectively limit the rate to 10 requests per seconds all the same. However, the client does not have to handle the 429 error and instead has to sometimes wait a bit longer.

About

Implementation of the Token Bucket algorithm in PHP.

Resources

License

Stars

Watchers

Forks

Languages

  • PHP 100.0%