vectorifyai/guzzle-rate-limiter

Guzzle middleware for preventive rate limiting with multi-store support, progressive delays, and cross-process coordination.

1.0.2 2025-07-17 14:05 UTC

Requires

• php: ^8.2
• guzzlehttp/guzzle: ^7.9
• monolog/monolog: ^3.9
• psr/log: ^3.0

Requires (Dev)

• illuminate/cache: ^10.0|^11.0|^12.0
• league/flysystem: ^3.0
• league/flysystem-memory: ^3.0
• phpunit/phpunit: ^11.5
• symfony/cache: ^7.0

Suggests

• illuminate/cache: For Laravel cache store integration
• league/flysystem: For filesystem-based cache store integration
• symfony/cache: For Symfony cache store integration

MIT

• symfony
• php
• api
• cache
• Guzzle
• rate limiting
• middleware
• laravel

README

A sophisticated Guzzle middleware for preventive rate limiting with multi-store support, progressive delays, and cross-process coordination. It works in accordance with the IETF standard by using the X-RateLimit-Remaining (number of requests remaining in the current rate limit window) and Retry-After (number of seconds to wait before retrying the request again) values available in the response headers.

Features

• Intelligent Rate Limiting: Progressive delays based on remaining API quota
• Multi-Store Support: InMemory, Laravel Cache, Symfony Cache, Filesystem, and more
• Cross-Process Coordination: Share rate limit state across multiple processes (i.e. queue jobs)
• Automatic Recovery: Handles 429 responses with exponential backoff
• Flexible Configuration: Customizable thresholds and delays
• PSR-3 Logging: Built-in logging with configurable levels

Installation

composer require vectorifyai/guzzle-rate-limiter

Quick Start

use GuzzleHttp\Client;
use GuzzleHttp\HandlerStack;
use Vectorify\GuzzleRateLimiter\RateLimiterMiddleware;
use Vectorify\GuzzleRateLimiter\Stores\InMemoryStore;

$stack = HandlerStack::create();
$stack->push(new RateLimiterMiddleware(new InMemoryStore));

$client = new Client([
    'handler' => $stack,
]);

Usage

Basic Usage

use Vectorify\GuzzleRateLimiter\RateLimiterMiddleware;
use Vectorify\GuzzleRateLimiter\Stores\InMemoryStore;

$middleware = new RateLimiterMiddleware(new InMemoryStore);

Laravel Integration

use Vectorify\GuzzleRateLimiter\Stores\LaravelStore;

$store = new LaravelStore(cache(), 'api:rate_limit');
$middleware = new RateLimiterMiddleware($store);

Symfony Integration

use Vectorify\GuzzleRateLimiter\Stores\SymfonyStore;
use Symfony\Component\Cache\Adapter\RedisAdapter;

$cache = new RedisAdapter(/* redis client */);
$store = new SymfonyStore($cache, 'api:rate_limit');
$middleware = new RateLimiterMiddleware($store);

Filesystem Integration

use Vectorify\GuzzleRateLimiter\Stores\FilesystemStore;
use League\Flysystem\Local\LocalFilesystemAdapter;

// Local filesystem
$adapter = new LocalFilesystemAdapter('/path/to/cache');
$store = new FilesystemStore($adapter);
$middleware = new RateLimiterMiddleware($store);

// AWS S3
use League\Flysystem\AwsS3V3\AwsS3V3Adapter;
$s3Adapter = new AwsS3V3Adapter($s3Client, $bucket, $prefix);
$store = new FilesystemStore($s3Adapter);

// SFTP
use League\Flysystem\PhpseclibV3\SftpAdapter;
$sftpAdapter = new SftpAdapter(/* SFTP connection settings */);
$store = new FilesystemStore($sftpAdapter);

Advanced Configuration

$middleware = new RateLimiterMiddleware(
    store: new InMemoryStore,
    cachePrefix: 'my_api:rate_limit',
    logger: $customLogger,
);

Changelog

Please see Releases for more information on what has changed recently.

Contributing

Pull requests are more than welcome. You must follow the PSR coding standards.

Security

Please review our security policy on how to report security vulnerabilities.

License

The MIT License (MIT). Please see LICENSE for more information.