PHPackages                             franzip/throttler - 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. [Utility & Helpers](/categories/utility)
4. /
5. franzip/throttler

ActiveLibrary[Utility & Helpers](/categories/utility)

franzip/throttler
=================

Simple rate limiter and usage tracker component.

1.0.1(2y ago)0158MITPHPPHP >=8.0.0

Since May 13Pushed 2y agoCompare

[ Source](https://github.com/franzip/throttler)[ Packagist](https://packagist.org/packages/franzip/throttler)[ Docs](http://github.com/franzip/throttler)[ RSS](/packages/franzip-throttler/feed)WikiDiscussions master Synced today

READMEChangelog (1)Dependencies (1)Versions (4)Used By (0)

[![Build Status](https://camo.githubusercontent.com/b0ec1e72446a6a80c1a5bc13c83db7b31c71ab4de660466d5d2763c3d529ef33/68747470733a2f2f7472617669732d63692e6f72672f6672616e7a69702f7468726f74746c65722e7376673f6272616e63683d6d6173746572)](https://travis-ci.org/franzip/throttler)[![Coverage Status](https://camo.githubusercontent.com/982732623c3528716a46fa441a91188ddcede46dec227789851352c7983ef4d9/68747470733a2f2f636f766572616c6c732e696f2f7265706f732f6672616e7a69702f7468726f74746c65722f62616467652e7376673f6272616e63683d6d6173746572)](https://coveralls.io/r/franzip/throttler?branch=master)

Throttler
=========

[](#throttler)

A simple, general purpose, rate limiter and usage tracker library.

Installing via Composer (recommended)
-------------------------------------

[](#installing-via-composer-recommended)

Install composer in your project:

```
curl -s http://getcomposer.org/installer | php

```

Create a composer.json file in your project root:

```
{
    "require": {
        "franzip/throttler": "1.0.*"
    }
}

```

Install via composer

```
php composer.phar install

```

Description
-----------

[](#description)

Once instantiated, the object must always be explicitly activated with the provided `start()` method.

Basically, you set a timeframe (it can be 24 hours, 2 seconds, 30 minutes, etc.), a global limit and the things you want to keep track of, and you're ready to go.

You can also set an additional limit that will applied as limit to each single component you are tracking.

You can change the given parameters only after you stop the current instance from tracking with the provided `stop()` method.

The `Throttler` will detect when a given timeframe is expired: all its internal states will be reset and a new timeframe will be computed.

If your code need to access any `Throttler` attributes, just use the provided getters (getName, getGlobalThreshold, etc.). See the constructor.

Constructor
-----------

[](#constructor)

```
$throttler = new Throttler($name, $globalThreshold, $metric, $metricFactor = 1,
                           $componentThreshold = null, $components = array());
```

Allowed $metric
---------------

[](#allowed-metric)

- 'sec': Compute the timeframe in (seconds \* $metricFactor)
- 'min': Compute the timeframe in (minutes \* $metricFactor)
- 'hrs': Compute the timeframe in (hours \* $metricFactor)

Basic Usage (default arguments)
-------------------------------

[](#basic-usage-default-arguments)

Example 1: using `Throttler` to cap incoming requests. The total amount of requests will be capped to 30 per hour.

```
use Franzip\Throttler\Throttler;

// Setting things up
// Max 30 total requests per hour
$throttler = new Throttler('requests', 30, 'hrs');

// Nothing happens and the call will return false since there is nothing to track
$throttler->start();

// Add remote addresses to track...
$throttler->addComponents('AddressToTrack1');
$throttler->addComponents('AddressToTrack2');
$throttler->addComponents('AddressToTrack3');
// Bulk adding
$throttler->addComponents(array('AddressToTrack4',
                                'AddressToTrack5',
                                'AddressToTrack6',
                                ...));
...

// Start tracking (timeframe starts now)
$throttler->start();

if ($throttler->updateComponent('AddressToTrack1')) {
    // handle update success
} else {
    // handle update failure
}

$numOfRequests = 31;

// will return false since the global limit is 30
$throttler->updateComponent('AddressToTrack1', $numOfRequests);

...

// Remove all stuff to track
$throttler->stop();
$throttler->setComponents(array());
```

Usage (custom arguments)
------------------------

[](#usage-custom-arguments)

Example 2: using `Throttler` to cap incoming requests.

The total amount of requests will be capped to 100 per day.

The amount of incoming requests from each address will be capped to 10 per day.

```
use Franzip\Throttler\Throttler;

// Setting things up
// Max 100 total requests per day
// Max 10 requests from each tracked address per day
$throttler = new Throttler('requests', 100, 'hrs', 24,
                           10, array('AddressToTrack1',
                                     'AddressToTrack2',
                                     ...));

// Start tracking (timeframe starts now)
$throttler->start();

if ($throttler->updateComponent('AddressToTrack1')) {
    // handle success
} else {
    // handle failure
}
```

isActive()
----------

[](#isactive)

Return whether tracking is turned on.

```
use Franzip\Throttler\Throttler;

$throttler = new Throttler('requests', 100, 'hrs');

// false
$throttler->isActive();

// false, there's nothing to track yet.
$throttler->start();

// false
$throttler->isActive();

$throttler->addComponents(array('foo', 'bar'));

// true, we have something to track
$throttler->start();

// true
$throttler->isActive();

// reset the instance (this will also stop tracking)
$throttler->reset();

// false
$throttler->isActive();
```

reset()
-------

[](#reset)

You can revert a `Throttler` object status to when it was instantiated. Just use the `reset()` method at anytime.

```
use Franzip\Throttler\Throttler;

$throttler = new Throttler('requests', 100, 'hrs');
// Change time cap to 2 hours
$throttler->setMetricFactor(2);
// Change time cap to 2 minutes
$throttler->setMetric('min');
// Change global limit to 50
$throttler->setGlobalThreshold(50);

...

$throttler->reset();
// reverted to 100
$throttler->getGlobalThreshold();
// reverted to 'hrs'
$throttler->getMetric();
```

TODOs
-----

[](#todos)

- A decent exceptions system.
- Move validation to external class.
- Allow bulk components adding.
- Refactoring messy tests.
- Refactoring update-checking methods.

License
-------

[](#license)

[MIT](http://opensource.org/licenses/MIT/ "MIT") Public License.

###  Health Score

23

—

LowBetter than 26% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity10

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity48

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% 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 ~0 days

Total

2

Last Release

781d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/815354e0dcecb447e841e032ed3f02a985239704fbbebbd6cd48c360efed5b95?d=identicon)[franzip](/maintainers/franzip)

---

Top Contributors

[![franzip](https://avatars.githubusercontent.com/u/6237296?v=4)](https://github.com/franzip "franzip (44 commits)")

---

Tags

trackingusagethrottletracker

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/franzip-throttler/health.svg)

```
[![Health](https://phpackages.com/badges/franzip-throttler/health.svg)](https://phpackages.com/packages/franzip-throttler)
```

###  Alternatives

[davedevelopment/stiphle

Simple rate limiting/throttling for php

2568.3M9](/packages/davedevelopment-stiphle)[bandwidth-throttle/token-bucket

Implementation of the Token Bucket algorithm.

5132.0M10](/packages/bandwidth-throttle-token-bucket)[zumba/amplitude-php

PHP SDK for Amplitude

4110.3M5](/packages/zumba-amplitude-php)[kyranb/footprints

A simple registration attribution tracking solution for Laravel (UTM Parameters and Referrers)

207372.2k](/packages/kyranb-footprints)[sunspikes/php-ratelimiter

A framework agnostic rate limiter for PHP

79689.1k1](/packages/sunspikes-php-ratelimiter)[bandwidth-throttle/bandwidth-throttle

Bandwidth throttle at application layer

87147.1k](/packages/bandwidth-throttle-bandwidth-throttle)

PHPackages © 2026

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