Json Rpc Endpoint Bundle Laravel Package

Getting Started

• Install with composer require tourze/json-rpc-endpoint-bundle. Because 2.0.0 is a major release, pin it explicitly ("^2.0") rather than floating, and diff the 1.0.0...2.0.0 changelog before upgrading an existing app.

• Look first at composer.json (confirm the PHP/Symfony/Laravel version constraints — this is a Symfony-style bundle, so in Laravel you'll typically register it through a bridge/service provider or a small adapter rather than a native Laravel package auto-discovery flow), then src/ for the endpoint controller, method resolver, and any PHP attributes used to mark exposed methods.

• Identify where the JSON-RPC route is registered (route loader, routes/ file, or config/routes*.yaml). In Laravel, mirror that route in routes/api.php pointing at the package's endpoint action so it sits behind your normal middleware stack.

• First use case: take one existing application service with a simple scalar-in/scalar-out method, annotate/expose it as a JSON-RPC method, and hit the endpoint with a raw curl POST:

  curl -X POST https://app.test/rpc \
    -H 'Content-Type: application/json' \
    -d '{"jsonrpc":"2.0","method":"user.get","params":{"id":1},"id":1}'
  

  Getting one method round-tripping end to end tells you more about the 2.0 API surface than reading the source top to bottom.

Implementation Patterns

• Attribute-driven registration. The bundle's model is to tag service methods as RPC methods (attribute or config map) and let the resolver build the dispatch table. Keep exposed methods on thin, dedicated "API" service classes rather than on domain services — it keeps the RPC surface auditable and avoids accidentally publishing internal methods.
• One endpoint, many methods. Treat the RPC endpoint as a single POST route and route by the method field. Put auth, throttling, and request-ID logging in HTTP middleware; put per-method authorization inside the method handler.
• Params as DTOs. Prefer typed parameter objects over associative arrays. Map params into a DTO, run Laravel validation on it, and throw a domain exception the bundle's error handler converts into a JSON-RPC error object. This keeps validation and error codes in one place.
• Error mapping. Decide early on your error-code scheme (reserved -32xxx codes for protocol errors vs. your own -32000..-32099 application range) and centralize the exception-to-code translation. Anything that leaks a stack trace into error.data is a bug.
• Notifications and batch. Support requests without an id (notifications must return an empty body, not null) and array payloads (batch) if clients need them; verify 2.0 behavior here specifically, as batch/notification handling is a common breaking-change area in major bumps.
• Testing. Write feature tests that POST raw JSON payloads and assert on result/error, not on HTTP status alone. Keep a small fixture set: success, validation failure, unknown method, unauthorized, notification, batch.
• Integration tip. If you're calling this from another Laravel app, wrap calls in a small client class that always sends jsonrpc: "2.0" and a monotonically increasing id, and throws on error — don't let callers hand-roll payloads.

Gotchas and Tips

• 2.0.0 has no narrative release notes, only a changelog diff link. Treat the upgrade as BC-breaking until proven otherwise: check for renamed namespaces/attributes, changed constructor signatures on the resolver/error handler, and dropped PHP/Symfony version support. Run your test suite against a branch before merging.
• JSON-RPC is not REST. Successful responses are HTTP 200 even when the body contains an error (for application-level errors). Don't build client error handling on status codes; parse error from the body. Some servers return 200 for protocol errors too — confirm which the bundle does so your monitoring isn't blind.
• HTTP status vs. error object mismatch is the most common source of "silent failure" reports. Log error.code and error.message server-side with the request payload.
• Symfony bundle in a Laravel app. Config keys, container tags, and service decoration won't be auto-wired. Expect to publish/translate config manually and be careful that decorating the resolver requires matching the exact interface from src/.
• Serialization of params. JSON objects vs. positional arrays change how the resolver binds arguments. Be consistent, and document it for clients — mixing the two is a frequent source of "works for me" bugs.
• Debugging. Log the raw request body before decoding, and enable the bundle's debug/verbose error mode only in local environments. Disable any "expose exception message" behavior in production.
• Extension points to look for: method resolver/mapping, error handler, and any middleware/hook for pre-dispatch logic. Prefer these over forking the endpoint controller — a fork will make the next major upgrade painful.
• Version drift risk. With a terse changelog and a single-maintainer bundle, pin to a commit or exact minor version in composer.lock and review diffs on every bump rather than trusting semver alone.