Advanced Json Rpc Laravel Package

Getting Started

Install via Composer: composer require felixfbecker/advanced-json-rpc. Start with the Dispatcher class — instantiate it with a target object (e.g., a service class), then call dispatch() with raw JSON-RPC request bodies. The first real-world use is exposing internal logic over JSON-RPC, especially for protocols like LSP where method names are hierarchical (textDocument/didOpen). A minimal working example:

use AdvancedJsonRpc\Dispatcher;

class Handler {
    public function hello(string $name): string {
        return "Hello, {$name}!";
    }
}

$dispatcher = new Dispatcher(new Handler());
echo $dispatcher->dispatch('{"jsonrpc":"2.0","id":1,"method":"hello","params":{"name":"World"}}');
// Output: "Hello, World!"

Implementation Patterns

• Nested Targets: Organize handlers into object hierarchies (e.g., TextDocumentManager under LanguageServer::$textDocument) to support methods like "textDocument/didOpen" using the -> delimiter. Configure this via constructor or setDelimiter('/') for LSP-style paths.
• Type Coercion: Leverage type-hints (string $uri, int $version) and @param annotations to auto-convert JSON params into typed PHP values. Use named object props or associative arrays — the underlying jsonmapper handles mapping.
• Error Handling: Wrap dispatch in try/catch to handle protocol-specific errors (ParseError, MethodNotFound, etc.) or convert uncaught exceptions to InternalError. Use Response::encode($result) to serialize valid responses or ErrorResponse for error payloads.
• Laravel Integration: Create a dedicated JsonRpcController that reads request()->getContent(), instantiates the dispatcher per-request (or via a singleton-aware factory), and returns a JSON response. Avoid conflating RPC with REST — treat it as a separate endpoint (e.g., /rpc) with custom middleware for auth/logging.

Gotchas and Tips

• Stale Dependency Risk: The package hasn’t had a release since 2021. Ensure compatibility with modern PHP (8.2+) and Laravel (10+) by manually testing — dependencies like netresearch/jsonmapper and phpdocumentor/reflection-docblock haven’t been updated in years and may conflict with newer ecosystem versions.
• No Framework Integration: There’s no Laravel service provider, middleware, or DI container integration. You must manually wire targets and manage request lifecycle. Avoid injecting services via constructor into targets — instantiate dependencies manually or use static factories.
• Missing Middleware Hooks: Authentication, rate limiting, and request validation aren’t built-in. Implement them in custom middleware that pre-processes requests before dispatching — but be aware the package doesn’t expose hooks like beforeDispatch or afterDispatch.
• Parameter Gotchas: Unnamed params (indexed arrays) require explicit @param annotations to avoid ambiguity. Optional params default to null if missing (fixed in v3.0.2+), but undocumented — always test edge cases like {"params":{}}.
• Debugging Tip: Enable strict mode in Dispatcher::__construct($target, '/', true) for additional validation. Log raw requests/responses early — the exception messages are terse but include error codes (e.g., -32601 for MethodNotFound) useful for tracing client-side issues.