A GuzzleHTTP Middleware that can delay requests before sending them.

0.4.1 2018-02-16 13:49 UTC

This package is auto-updated.

Last update: 2022-01-24 13:49:19 UTC


Latest Stable Version License Build Status Coverage Status Quality Score Total Downloads

Guzzle Throttle Middleware

This middleware adds throttling capabilities to your Guzzle client.

This can be useful when some hosts limits your number of requests per second / per minute.


composer require bentools/guzzle-throttle-middleware

Counter storage

By default, request counters are stored in an array.

But you can use the PSR6Adapter to store your counters within a psr/cache implementation, such as symfony/cache, and use shared storages like Redis, APCu, Memcached, ...


For this middleware to work, you need to register some configurations.

A configuration is composed of:

  • A Request matcher (to trigger or not the throttler, depending on the request content)
  • A maximum number of requests
  • The period, in seconds, during which the maximum number of requests apply.
  • A storage key.

You can register as many configurations as you need. The 1st request matcher wins.


namespace App\RequestMatcher;

use BenTools\Psr7\RequestMatcherInterface;
use Psr\Http\Message\RequestInterface;

class ExampleOrgRequestMatcher implements RequestMatcherInterface
     * @inheritDoc
    public function matchRequest(RequestInterface $request)
        return false !== strpos($request->getUri()->getHost(), '');
use App\RequestMatcher\ExampleOrgRequestMatcher;
use BenTools\GuzzleHttp\Middleware\Storage\Adapter\ArrayAdapter;
use BenTools\GuzzleHttp\Middleware\ThrottleConfiguration;
use BenTools\GuzzleHttp\Middleware\ThrottleMiddleware;
use GuzzleHttp\Client;
use GuzzleHttp\HandlerStack;

require_once __DIR__ . '/vendor/autoload.php';

$stack = HandlerStack::create();
$middleware = new ThrottleMiddleware(new ArrayAdapter());

// Max 1 request per second
$maxRequests = 1;
$durationInSeconds = 1;
    new ThrottleConfiguration(new ExampleOrgRequestMatcher(), $maxRequests, $durationInSeconds, 'example')

$stack->push($middleware, 'throttle');
$client = new Client([
    'handler' => $stack,

$client->get(''); // Will be executed immediately
$client->get(''); // Will be executed in 1 second



Known issues

Due to PHP's synchronous behaviour, remember that throttling means calling sleep() or usleep() functions, which will delay your entire script, and not only the current request.

This means throttling will also block Guzzle's asynchronous requests when using CurlMultiHandler.

To prevent this, you may have a look at bentools/guzzle-queue-handler, a handler that delegates asynchronous requests to PHP workers (Beanstalk, RabbitMQ, Redis, ...).

You can then enable throttling only on workers.

See also