PHPackages                             villermen/token-bucket - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. villermen/token-bucket

Abandoned → [symfony/rate-limiter](/?search=symfony%2Frate-limiter)ArchivedLibrary

villermen/token-bucket
======================

Implementation of the token bucket algorithm.

3.0.0(5y ago)02WTFPLPHPPHP >=7.2.5

Since Jun 19Pushed 2y agoCompare

[ Source](https://github.com/Webador/token-bucket)[ Packagist](https://packagist.org/packages/villermen/token-bucket)[ Docs](https://github.com/jouwweb/token-bucket)[ RSS](/packages/villermen-token-bucket/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (2)Dependencies (7)Versions (11)Used By (0)

Caution

This project is archived. Please implement the more recent [symfony/rate-limiter](https://github.com/symfony/rate-limiter). It also implements the token bucket algorithm and enjoys better support.

Token Bucket
============

[](#token-bucket)

This is a fork of [bandwidth-throttle/token-bucket](https://github.com/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](https://en.wikipedia.org/wiki/Token_bucket) 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
============

[](#installation)

Use [Composer](https://getcomposer.org/):

```
composer require jouwweb/token-bucket
```

Example
-------

[](#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
----------------

[](#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.

###  Health Score

27

—

LowBetter than 49% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity2

Limited adoption so far

Community12

Small or concentrated contributor base

Maturity64

Established project with proven stability

 Bus Factor1

Top contributor holds 77.4% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~205 days

Recently: every ~358 days

Total

10

Last Release

2123d ago

Major Versions

0.4 → 1.0.02016-06-27

1.1.1 → 2.0.02017-10-13

2.1.0 → 3.0.02020-07-15

PHP version history (4 changes)0.1PHP >=5.4

0.3PHP >=5.5

1.0.0PHP >=5.6

3.0.0PHP >=7.2.5

### Community

Maintainers

![](https://www.gravatar.com/avatar/212c27b557d8126e053ac3ed5491944ec8bccd1b8bb910e807934786233f3020?d=identicon)[Villermen](/maintainers/Villermen)

---

Top Contributors

[![malkusch](https://avatars.githubusercontent.com/u/1623984?v=4)](https://github.com/malkusch "malkusch (89 commits)")[![villermen](https://avatars.githubusercontent.com/u/1106303?v=4)](https://github.com/villermen "villermen (21 commits)")[![drsect0r](https://avatars.githubusercontent.com/u/9106228?v=4)](https://github.com/drsect0r "drsect0r (1 commits)")[![austinpray](https://avatars.githubusercontent.com/u/2192970?v=4)](https://github.com/austinpray "austinpray (1 commits)")[![roelvanduijnhoven](https://avatars.githubusercontent.com/u/91910?v=4)](https://github.com/roelvanduijnhoven "roelvanduijnhoven (1 commits)")[![lloy0076](https://avatars.githubusercontent.com/u/1174532?v=4)](https://github.com/lloy0076 "lloy0076 (1 commits)")[![deefour](https://avatars.githubusercontent.com/u/14762?v=4)](https://github.com/deefour "deefour (1 commits)")

---

Tags

rate limitthrottlethrottlingrate limitingbandwidthtoken bucket

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/villermen-token-bucket/health.svg)

```
[![Health](https://phpackages.com/badges/villermen-token-bucket/health.svg)](https://phpackages.com/packages/villermen-token-bucket)
```

###  Alternatives

[bandwidth-throttle/token-bucket

Implementation of the Token Bucket algorithm.

5121.9M10](/packages/bandwidth-throttle-token-bucket)[davedevelopment/stiphle

Simple rate limiting/throttling for php

2567.7M9](/packages/davedevelopment-stiphle)[graham-campbell/throttle

Throttle Is A Rate Limiter For Laravel

7102.3M11](/packages/graham-campbell-throttle)[maba/gentle-force-bundle

Symfony bundle that integrates gentle-force library for limiting both brute-force attempts and ordinary requests, using leaky/token bucket algorithm, based on Redis

53517.6k1](/packages/maba-gentle-force-bundle)[maba/gentle-force

Library for limiting both brute-force attempts and ordinary requests, using leaky/token bucket algorithm, based on Redis

45591.0k2](/packages/maba-gentle-force)[sunspikes/php-ratelimiter

A framework agnostic rate limiter for PHP

76674.1k1](/packages/sunspikes-php-ratelimiter)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)