The Throttler class provides a very simple way to limit an activity to be performed a certain amount of attempts within a set time limit. This is most often used for performing rate limiting on API’s, or restricting the number of attempts a user can make against a form to help prevent brute force attacks. The class itself can be used for anything that you need to throttle based on actions within a set time interval.


The Throttler implements a simplified version of the Token Bucket algorithm. This basically treats each action that you want as a bucket. When you call the check() method, you tell it how large the bucket is, and how many tokens it can hold and the time interval. Each check() call uses 1 of the available tokens, by default. Let’s walk through an example to make this clear.

Let’s say we want an action to happen once every second. The first call to the Throttler would look like the following, with the first parameter being the bucket name, the second parameter the number of tokens the bucket holds, and the third being the amount of time it takes for the bucket to refill:

$throttler = \Config\Services::throttler();
$throttler->check($name, 60, MINUTE);

Here we’re using one of the global constants for the time, to make it a little more readable. This says that the bucket allows 60 actions every minute, or 1 action every second.

Let’s say that a third-party script was trying to hit a URL repeatedly. At first, it would be able to use all 60 of those tokens in less than a second. However, after that the Throttler would only allow one action per second, potentially slowing down the requests enough that they attack is no longer worth it.


For the Throttler class to work, the Cache library must be setup to use a handler other than dummy. For best performance, an in-memory cache, like Redis or Memcached, is recommended.

Rate Limiting

The Throttler class does not do any rate limiting or request throttling on its own, but is the key to making one work. An example Filter is provided that implements very simple rate limiting at one request per second per IP address. Here we will run through how it works, and how you could set it up and start using it in your application.

The Code

You can find this file at application/Filters/Throttle.php but the relevant method is reproduced here:

public function before(RequestInterface $request)
    $throttler = Services::throttler();

    // Restrict an IP address to no more
    // than 1 request per second across the
    // entire site.
    if ($throttler->check($request->getIPAddress(), 60, MINUTE) === false)
        return Services::response()->setStatusCode(429);

When ran, this method first grabs an instance of the throttler. Next it uses the IP address as the bucket name, and sets things to limit them to one request per second. If the throttler rejects the check, returning false, then we return a Response with the status code set to 429 - Too Many Attempts, and the script execution ends before it ever hits the controller. This example will throttle based on a single IP address across all requests made to the site, not per page.

Applying the Filter

We don’t necessarily need to throttle every page on the site. For many web applications this makes the most sense to apply only to POST requests, though API’s might want to limit to every request made by a user. In order to apply this to incoming requests, you need to edit /application/Config/Filters.php and first add an alias to the filter:

public $aliases = [
            'csrf'    => \App\Filters\CSRF::class,
            'toolbar' => \App\Filters\DebugToolbar::class,
    'throttle' => \App\Filters\Throttle::class

Next, we assign it to all POST requests made on the site:

public $methods = [
    'post' => ['throttle', 'CSRF']

And that’s all there is to it. Now all POST requests made on the site will have be rate limited.

Class Reference

check(string $key, int $capacity, int $seconds[, int $cost = 1])
  • $key (string) – The name of the bucket
  • $capacity (int) – The number of tokens the bucket holds
  • $seconds (int) – The number of seconds it takes for a bucket to completely fill
  • $cost (int) – The number of tokens that are spent for this action

TRUE if action can be performed, FALSE if not

Return type:


Checks to see if there are any tokens left within the bucket, or if too many have been used within the allotted time limit. During each check the available tokens are reduced by $cost if successful.

Returns:The number of seconds until another token should be available.
Return type:integer

After check() has been ran and returned FALSE, this method can be used to determine the time until a new token should be available and the action can be tried again.

In this case, the minimum enforced wait time is one second.