NewWe open-sourced 50+ Laravel packages
Custom AI apps, agents and automation — Roundly ConsultingRoundly
All packages

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

KeyDefaultEnvPurpose
limiters[]—Named limiter profiles referenced by string.
storeInMemoryStore::classHTTP_CLIENT_RATE_LIMITS_STOREDefault store for new rate limits (must implement Store; unset or blank = InMemoryStore).
deferrerSleepDeferrer::classHTTP_CLIENT_RATE_LIMITS_DEFERRERDefault deferrer for new rate limits (must implement Deferrer; unset or blank = SleepDeferrer).
cache_storenullHTTP_CLIENT_RATE_LIMITS_CACHE_STORECache store used by CacheStore (null, unset or blank = the default cache store).
cache_prefixhttp-client-rate-limitsHTTP_CLIENT_RATE_LIMITS_CACHE_PREFIXKey prefix used by CacheStore.
redis_connectiondefaultHTTP_CLIENT_RATE_LIMITS_REDIS_CONNECTIONRedis connection the RedisStore uses.
database_connectionnullHTTP_CLIENT_RATE_LIMITS_DATABASE_CONNECTIONDatabase connection the DatabaseStore uses (null, unset or blank = the default connection).
events_enabledtrueHTTP_CLIENT_RATE_LIMITS_EVENTS_ENABLEDDispatch 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=true

Inspecting 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-limits

Show 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 crypto

By 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.