Configuration Reference

Configuration is passed as a PHP array to Config, or loaded from a file via Config::fromFile().

$config = Config::fromFile('config.php');
// or
$config = new Config([ /* overrides */ ]);

Config::fromFile() throws RuntimeException if the file is missing or returns non-array data. Unspecified keys fall back to defaults.

Merged Default Configuration

return [
    'handlers' => [
        'paths' => [],
        'namespace' => 'App\\Handlers\\',
        'method_separator' => '.',
    ],
    'auth' => [
        'enabled' => false,
        'driver' => 'jwt',
        'protected_methods' => [],
        'jwt' => [
            'secret' => '',
            'algorithm' => 'HS256',
            'header' => 'Authorization',
            'prefix' => 'Bearer ',
            'issuer' => '',
            'audience' => '',
            'leeway' => 0,
        ],
        'api_key' => [
            'header' => 'X-API-Key',
            'keys' => [],
        ],
        'basic' => [
            'header' => 'Authorization',
            'users' => [],
        ],
    ],
    'batch' => [
        'max_items' => 100,
    ],
    'limits' => [
        'max_body_size' => 1048576,
        'max_json_depth' => 64,
    ],
    'logging' => [
        'enabled' => true,
        'level' => 'info',
        'path' => 'logs/app.log',
        'sanitize_secrets' => true,
    ],
    'log_rotation' => [
        'enabled' => true,
        'max_size' => 10485760,
        'max_files' => 5,
        'compress' => true,
    ],
    'compression' => [
        'request_gzip' => true,
        'response_gzip' => false,
    ],
    'rate_limit' => [
        'enabled' => false,
        'max_requests' => 100,
        'window_seconds' => 60,
        'strategy' => 'ip',
        'storage_path' => 'storage/rate_limit',
        'batch_weight' => 1,
        'fail_open' => false,
    ],
    'debug' => false,
    'notifications' => [
        'enabled' => true,
        'log' => true,
    ],
    'response_fingerprint' => [
        'enabled' => false,
        'algorithm' => 'sha256',
    ],
    'health' => [
        'enabled' => true,
    ],
    'validation' => [
        'strict' => false,
        'schema' => [
            'enabled' => false,
        ],
    ],
    'content_type' => [
        'strict' => false,
    ],
    'hooks' => [
        'enabled' => true,
        'isolate_exceptions' => true,
    ],
    'server' => [
        'version' => '1.0.0',
        'name' => 'Lumen JSON-RPC',
        'url' => '',
    ],
];

These are the library's merged defaults. In real applications you will normally set handlers.paths explicitly and often override file-system paths such as logging.path or rate_limit.storage_path to match your deployment layout.

Section Details

handlers

Auto-discovery scans only the top-level PHP files inside each configured handler path. Nested subdirectories are ignored.

auth

The built-in JWT decoder supports HMAC algorithms only. Install firebase/php-jwt if you need additional algorithm support.

Use exact names like user.get to protect a single procedure, or prefixes ending in the method separator like user. to protect a whole handler namespace.

For Basic auth, prefer storing precomputed password_hash values. Plaintext password entries remain supported for development and test setups.

batch

When a batch request exceeds max_items, the server returns a single -32600 Invalid Request error with a data field indicating the maximum allowed.

Batch behavior summary:

limits

logging

log_rotation

compression

Gzip support requires the zlib extension (ext-zlib), which is an optional dependency. If the extension is not available, gzip features are gracefully disabled.

rate_limit

When rate-limited, the server returns HTTP 429 with a -32000 JSON-RPC error and X-RateLimit-Limit, X-RateLimit-Remaining, Retry-After headers.

fail_open defaults to false, so the built-in file limiter denies requests when storage cannot be opened or locked. Set it to true only if your deployment explicitly prefers availability over strict limit enforcement during storage failures.

Custom rate limit backends

The rate limiter backend is pluggable via RateLimiterInterface. Use the stable JsonRpcServer::setRateLimiter() entry point to swap in a custom backend:

use Lumen\JsonRpc\RateLimit\RateLimiterInterface;
use Lumen\JsonRpc\RateLimit\RateLimitResult;

class RedisRateLimiter implements RateLimiterInterface
{
    public function check(string $key): RateLimitResult
    {
        return $this->checkAndConsume($key, 1);
    }

    public function checkAndConsume(string $key, int $weight): RateLimitResult
    {
        // Your Redis-backed implementation
    }
}

$server->setRateLimiter(new RedisRateLimiter(...));

An InMemoryRateLimiter is included for testing and single-process use cases.

debug

notifications

response_fingerprint

Clients can use If-None-Match for conditional requests. A matching ETag returns HTTP 304 (non-batch single requests only). When response gzip negotiation is active, ETags are representation-specific and the conditional response preserves Vary: Accept-Encoding so caches keep the representation metadata aligned.

health

When health.enabled is false, GET / is not advertised in the Allow header on 405 Method Not Allowed responses; only POST remains listed.

validation

When schema.enabled is true, handlers implementing RpcSchemaProviderInterface will have their parameters validated against declared schemas before invocation. Errors produce a -32602 Invalid params response.

The built-in validator is intentionally a lightweight JSON Schema subset for runtime request validation, not a full JSON Schema implementation.

content_type

HTTP status codes are used for transport-level outcomes only. JSON-RPC parse/protocol/application errors still return HTTP 200 with a JSON-RPC error body, while all-notification batches return 204, conditional fingerprint matches return 304, and rate-limited requests return 429.

hooks

Hook callbacks run inline with request processing. By default, a thrown hook exception is logged and suppressed so later hooks and request handling can continue. Set hooks.isolate_exceptions to false if you need fail-fast hook behavior.

server