Configuration
The package works with zero configuration. The published config/http-client-rate-limits.php in full:
use RoundlyConsulting\HttpClientRateLimits\Deferrer\SleepDeferrer;
use RoundlyConsulting\HttpClientRateLimits\Store\InMemoryStore;
return [
// Named limiter profiles referenced by string: Http::rateLimit('github').
// Each is ['rate' => int, 'per' => second|minute|hour|day] plus optional
// 'by', 'trim', 'max_wait' (ms), 'jitter' (ms), 'adaptive' (bool).
'limiters' => [
// 'github' => ['rate' => 5, 'per' => 'second', 'by' => null],
],
// Default Store for every limit the manager builds (RateLimits::…, Http::rateLimit()).
// Must implement RoundlyConsulting\HttpClientRateLimits\Store\Store.
'store' => env('HTTP_CLIENT_RATE_LIMITS_STORE', InMemoryStore::class),
// Default Deferrer used to read "now" and to pause when a limit is hit.
// Must implement RoundlyConsulting\HttpClientRateLimits\Deferrer\Deferrer.
'deferrer' => env('HTTP_CLIENT_RATE_LIMITS_DEFERRER', SleepDeferrer::class),
// Cache store name (from config/cache.php) and key prefix used by the CacheStore.
'cache_store' => env('HTTP_CLIENT_RATE_LIMITS_CACHE_STORE'),
'cache_prefix' => env('HTTP_CLIENT_RATE_LIMITS_CACHE_PREFIX', 'http-client-rate-limits'),
// Redis connection name (from config/database.php) used when the store is the RedisStore.
'redis_connection' => env('HTTP_CLIENT_RATE_LIMITS_REDIS_CONNECTION', 'default'),
// Database connection name used when the store is the DatabaseStore (null = default).
'database_connection' => env('HTTP_CLIENT_RATE_LIMITS_DATABASE_CONNECTION'),
// Dispatch RequestDeferred / RequestAllowed / RateLimitReset events when the limiter runs.
'events_enabled' => env('HTTP_CLIENT_RATE_LIMITS_EVENTS_ENABLED', true),
];Every key
| Key | Default | Env | Purpose |
|---|---|---|---|
limiters | [] | — | Named limiter profiles referenced by string. |
store | InMemoryStore::class | HTTP_CLIENT_RATE_LIMITS_STORE | Default store for new rate limits (must implement Store; unset or blank = InMemoryStore). |
deferrer | SleepDeferrer::class | HTTP_CLIENT_RATE_LIMITS_DEFERRER | Default deferrer for new rate limits (must implement Deferrer; unset or blank = SleepDeferrer). |
cache_store | null | HTTP_CLIENT_RATE_LIMITS_CACHE_STORE | Cache store used by CacheStore (null, unset or blank = the default cache store). |
cache_prefix | http-client-rate-limits | HTTP_CLIENT_RATE_LIMITS_CACHE_PREFIX | Key prefix used by CacheStore. |
redis_connection | default | HTTP_CLIENT_RATE_LIMITS_REDIS_CONNECTION | Redis connection the RedisStore uses. |
database_connection | null | HTTP_CLIENT_RATE_LIMITS_DATABASE_CONNECTION | Database connection the DatabaseStore uses (null, unset or blank = the default connection). |
events_enabled | true | HTTP_CLIENT_RATE_LIMITS_EVENTS_ENABLED | Dispatch RequestDeferred / RequestAllowed / RateLimitReset events. Accepts true/false, 1/0, on/off, yes/no; a blank value keeps the default (true); anything else throws InvalidConfigurationException. |
A configured store or deferrer that doesn’t implement the matching contract throws a typed InvalidStoreException / InvalidDeferrerException (both extend RateLimitException) when a rate limit is created. A limit must allow at least one request per window: a rate / max attempts below 1 throws InvalidLimitException.
The four store settings — cache_store, cache_prefix, redis_connection and database_connection — are read strictly when the matching store is resolved: a non-string value throws an InvalidConfigurationException naming the key. Blank means not set: an absent key, null and a blank value (a host’s KEY=, empty or whitespace only) all use the default, for every key in the table above (a blank events_enabled keeps events on).
Choosing a store
Pick the default store in the published config. For example, share limits through a cache store you already run:
use RoundlyConsulting\HttpClientRateLimits\Store\CacheStore;
// config/http-client-rate-limits.php
'store' => CacheStore::class,
'cache_store' => 'redis', // any store from config/cache.php (null = default)
'cache_prefix' => 'http-client-rate-limits',Environment
The store, deferrer, cache, Redis, database and events settings are env-driven, so you can tune them per environment without publishing the config:
HTTP_CLIENT_RATE_LIMITS_CACHE_STORE=redis
HTTP_CLIENT_RATE_LIMITS_CACHE_PREFIX=http-client-rate-limits
HTTP_CLIENT_RATE_LIMITS_REDIS_CONNECTION=default
HTTP_CLIENT_RATE_LIMITS_DATABASE_CONNECTION=limits
HTTP_CLIENT_RATE_LIMITS_EVENTS_ENABLED=trueInspecting the active setup
The package adds its own section to php artisan about, reporting the active store, deferrer, number of limiter profiles and whether events are enabled:
php artisan about --only=http-client-rate-limitsShow your open-source love
This package is free and MIT-licensed. If it saves you time, a one-off donation or a Patreon membership keeps it maintained, tested and documented.
More ways to support, including cryptoBy donating, you agree to our donation terms.
Want this built into your product?
We integrate our packages into custom Laravel and AI builds. Tell us what you're working on and we'll reply within 48 hours.