PHP TokenBucket implementation for rate limit

1.0.0 2016-09-28 02:57 UTC

This package is auto-updated.

Last update: 2021-10-11 21:44:38 UTC


TokenBucket is an algorithm for rate limit

You can check algorithm from http://en.wikipedia.org/wiki/Token_bucket


Basic usage


use TokenBucket\TokenBucket;
use TokenBucket\Storage\Memcached as MemcachedStorage;

$storage = new MemcachedStorage();

// Define the bucket
$options = array(
    'capacity' => 20,
    'fillRate' => 5

// Create the bucket
$bucket = new TokenBucket('key-for-bucket', $storage, $options);

// Check if token is avaible
if ($bucket->consume()===false) {
    //Not allowed!!

// ...


capacity : Max token count of bucket.

fillRate : Token count to fill per second. For example if capacity is 20 and fillRate is 5, 5 tokens will added to bucket every second. But, total token cannot be exceed 20.

ttl : Time to live for bucket in seconds. If not given or zero given, it will be calculated automatically according to capacity and fillRate. ttl can be used to reset bucket with capacity. For example: if capacity is 100 and fillRate is zero and ttl is 300, 100 token can be consumed at 300 seconds. After 300 seconds, bucket will be reset to capacity.

Rate Limit Http Headers

You can get http headers for rate limit with getRateLimitHttpHeaders method:

X-RateLimit-Limit : gives capacity of bucket

X-RateLimit-Remaining : allowed token count of bucket

X-RateLimit-Reset : time to live of bucket


You can contribute by forking the repo and creating pull requests. You can also create issues or feature requests.


This project is licensed under the MIT license. LICENSE file can be found in this repository.