Handlers & Method Naming

handler.method pattern

Methods follow the handler.method pattern. When you see user.get:

• Handler class User
• Method get()
• In your configured handlers path

Handler safety rules

• Methods starting with rpc. are always rejected
• Method names must match handler.method
• Magic methods (__construct, __call, etc.) are blocked
• Only public instance methods on the concrete handler class are callable
• Static methods are excluded
• Inherited methods are excluded

Parameter binding

Parameters are type-checked and mapped to -32602 Invalid params for mismatches.

• Wrong scalar types produce -32602
• Missing required parameters produce -32602
• Unknown named parameters produce -32602
• Surplus positional parameters produce -32602
• Optional parameters use their defaults when omitted
• Both positional and named parameters are supported
• int to float coercion is allowed
• RequestContext is injected automatically when declared as the first method parameter

Explicit procedure descriptors

For advanced use cases, you can register procedures explicitly alongside auto-discovery:

use Lumen\JsonRpc\Dispatcher\ProcedureDescriptor;

$registry = $server->getRegistry();
$registry->register('math.add', MathHandler::class, 'add', [
    'description' => 'Add two numbers',
]);

Handler factory (DI)

Inject app services into handlers without forcing a framework container:

use Lumen\JsonRpc\Dispatcher\HandlerFactoryInterface;

$factory = new class($db) implements HandlerFactoryInterface {
    public function __construct(private DatabaseService $db) {}

    public function create(string $className, RequestContext $context): object
    {
        return new $className($this->db);
    }
};
$server->setHandlerFactory($factory);