---
title: "Configuration — HTTP Client Rate Limits for Laravel | Roundly"
description: "Every config key, its default and env variable — limiter profiles, default store and deferrer, cache, Redis, database and events."
url: https://roundly-consulting.com/open-source/docs/http-client-rate-limits-for-laravel/configuration
language: en
---

[All packages](https://roundly-consulting.com/open-source.md)

[HTTP Client Rate Limits for Laravel](https://roundly-consulting.com/open-source/docs/http-client-rate-limits-for-laravel.md)

# Configuration

The package works with zero configuration. The published config/http-client-rate-limits.php in full:

```php
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; without by, each is keyed by its own name. |
| `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:

```php
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:

```bash
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:

```bash
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](https://roundly-consulting.com/support-us.md)

By donating, you agree to our [donation terms](https://roundly-consulting.com/donation-terms.md).

[Support our open source work (opens in a new tab)](https://donate.stripe.com/dRmeVe8FX5PF1Qd9pXcEw00) [Join us on Patreon (opens in a new tab)](https://www.patreon.com/cw/roundly)

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

[Get a quote in 48 hours](https://roundly-consulting.com/contact.md) [Browse all packages](https://roundly-consulting.com/open-source/docs/http-client-rate-limits-for-laravel.md)