Advanced Json Rpc Laravel Package

Getting Started

Start by installing the package via Composer:

composer require danog/advanced-json-rpc

The core entry point is the AdvancedJsonRpc\Dispatcher class. For a minimal HTTP-based JSON-RPC endpoint (e.g., POST /rpc), inject your target service/controller into the dispatcher and call dispatch() with the raw request body:

use AdvancedJsonRpc\Dispatcher;

$target = new MyRpcService();
$dispatcher = new Dispatcher($target);

$requestBody = (string) $request->getBody(); // PSR-7 request
$result = $dispatcher->dispatch($requestBody);

return $response->withJson($result); // Return PSR-7 response

Review the README examples first—especially the someMethod(Argument $arg) pattern—since automatic type coercion via PHP type hints and @param is the library’s flagship feature.

Implementation Patterns

• HTTP Gateway Layer: Wrap the dispatcher in a Laravel controller or middleware. Parse the request, dispatch, and convert results/errors to JSONRPC-compliant responses using Result, Error, and BatchResult classes.
• Nested Namespaces for LSP-Style APIs: Model your service layer hierarchically (e.g., $server->textDocument, $server->workspace), then route calls like textDocument/didOpen by setting setDelimiter('/'). This avoids method-name collisions and improves discoverability.
• Type-Aware Parameter Binding: Define DTOs with public properties (or annotated getters/setters) and use native type hints (string $uri, array $params) or docblock @param tags for deserialization. The internal JsonMapper handles coercion from request params → typed object.
• Extensibility Hooks: Extend Dispatcher to customize behavior (e.g., inject Laravel’s service container for target instantiation, or intercept method resolution). For per-call DI, override createTarget() or use a factory function.
• Error Handling Strategy: Catch Exceptions from dispatch() and map them to Error objects (code, message, data). Use JsonMapperException and MethodNotFoundException for granular error routing.

Gotchas and Tips

• Public Properties Only: JsonMapper only populates public properties. Private/protected properties require manual normalization or @param getters/setters. Audit DTOs early—this trips up most new users.
• No Auth/Zap/Security Layer: This is only protocol logic. Add auth/rate limiting around the dispatcher (e.g., middleware) rather than expecting built-in support.
• Delimiter Global Effect: Calling setDelimiter('/') affects all subsequent method resolution—including -> in method names if not handled. Avoid mixing delimiters; prefer one convention (e.g., / for LSP, -> for internal service calls).
• Limited Union/Intersection Support: Complex types like int|bool or class-string<Interface> may fail coercion. Prefer explicit, simple types; validate domain constraints after deserialization.
• Debugging Hidden Failures: When params deserialization fails, check JsonMapperException details—it often fails silently on missing/extra fields. Temporarily enable JsonMapper’s strictNullTypes or debug via var_dump() in a custom Dispatcher subclass.
• Adoption Caution: With only 13 stars and 0 dependents, prioritize reviewing the test suite (tests/) and locking to a specific commit/tag for production use until broader adoption is proven.