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.

Full Configuration

return [
    'handlers' => [
        'paths' => [__DIR__ . '/../handlers'],
        'namespace' => 'App\\Handlers\\',
        'method_separator' => '.',
    ],
    'auth' => [
        'enabled' => false,
        'driver' => 'jwt',
        'protected_methods' => ['user.', 'order.'],
        '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' => __DIR__ . '/../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' => __DIR__ . '/../storage/rate_limit',
        'batch_weight' => 1,
        'fail_open' => true,
    ],
    'debug' => false,
    'notifications' => [
        'enabled' => true,
        'log' => true,
    ],
    'response_fingerprint' => [
        'enabled' => false,
        'algorithm' => 'sha256',
    ],
    'health' => [
        'enabled' => true,
    ],
    'validation' => [
        'strict' => true,
        'schema' => [
            'enabled' => false,
        ],
    ],
    'content_type' => [
        'strict' => false,
    ],
    'hooks' => [
        'enabled' => true,
    ],
    'server' => [
        'version' => '1.0.0',
        'name' => 'Lumen JSON-RPC',
    ],
];

Section Details

handlers

auth

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

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.

Custom rate limit backends

The rate limiter backend is pluggable via RateLimiterInterface. To use 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->getEngine()->getRateLimitManager()->setLimiter(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).

health

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.

content_type

hooks

server