Json Rpc Laravel Package

Product Decisions This Supports

• Build vs. buy the protocol layer: Still the core call, and this release makes the "buy" side easier to defend. JSON-RPC 2.0 framing (envelopes, batch, notifications, error codes, positional vs. named params) is well-specified but tedious to reimplement. The library now ships with 366 tests, 100% line coverage enforced in CI, PHPStan at max with no baseline, and transports exercised against real HTTP servers rather than mocks. Decision: buy the wire format, build the domain layer.
• Integration strategy for partner/legacy APIs: Unchanged in rationale — JSON-RPC is what partner APIs, enterprise middleware, crypto/blockchain nodes, and internal service meshes actually speak. What this release adds is incident avoidance: compressed bodies are now reported as compressed rather than malformed, a JSON-RPC error object survives a 500 instead of being replaced by the status code, and a response carrying another request's id (or non-answer JSON) is refused rather than surfacing as a null result. Those are exactly the failure modes that generate "why is the integration returning nulls?" support tickets. That is a real reduction in the total cost of ownership we are signing up for.
• Exposing internal capabilities as an RPC gateway: Stronger than before. Server-side fixes — variadic procedures accepting named parameters, procedures with numeric-looking names registrable via the array helpers, withAuthenticationHeader() reading a forwarded Basic <base64> scheme — mean the dispatcher now fits ordinary handler shapes instead of only toy ones. Still compare against GraphQL (better for flexible client-driven queries) and REST (better for public, cacheable, documented APIs).
• New decision this release forces — our parameter-typing posture: v2 no longer coerces parameters. A client sending ["5", "3"] to function (int $a, int $b) now receives -32602 Invalid params. If we expose an RPC surface to lenient clients, this is a product compatibility decision, not just an upgrade chore: either commit to a strict, versioned contract (cleanest, and what we should prefer), stay on 1.x for that surface, or put a coercion adapter in our own handler layer where we can change our mind later.
• Version and lifecycle decision: 2.0 is a beta, cut from the 2.x branch via an open PR (#29), and the release itself states the API may still move before 2.0.0. So the real decision is not "adopt 2.0" but "adopt a pinned beta for internal and non-critical paths now, or hold on 1.x until 2.0.0 final." Do not put a beta on a path where an API move costs us a customer-facing release. Keep the upgrade guide (UPGRADE-2.0.md) in the migration ticket, not just the composer bump.
• Make vs. wrap for Laravel: The glue-work estimate holds (~1–3 days: service provider, config, client facade, handler registry). Wrapping is now more valuable, because the library's surface has grown — multiple client transports, a server component, cookie handling — and every one of those is a thing we do not want controllers touching directly. Correspondingly, "read it in an afternoon and vendor it" is now an overstatement; the code is still small enough to own, but it is no longer a one-sitting read.
• Where NOT to spend: Unchanged. Not for public-facing APIs needing OpenAPI docs, HTTP caching, or API-key/rate-limit middleware out of the box; not for latency-critical or high-throughput paths.

When to Consider This Package

Consider it when:

• The counterparty already speaks JSON-RPC 2.0 and there is no REST/GraphQL alternative.
• The integration is internal, low-to-medium traffic, and synchronous request/response is sufficient.
• You need batch requests, notifications, or strict JSON-RPC error-code semantics without hand-rolling them.
• You need transport robustness you would otherwise write yourself: gzip handling, short/contradictory body detection, error objects preserved through 5xx, wrong-id and non-JSON responses rejected.
• You are standing up a server and need named parameters for variadic procedures or scheme-prefixed auth headers forwarded from a gateway.
• Your reviewer, security board, or staff engineer will ask "what is the quality bar, and can we audit it?" — 100% coverage enforced in CI, static analysis at max level, and real-server transport tests are an answer.
• MIT-licensed, dependency-light, framework-neutral code is a requirement; timeline is short; the alternative is a bespoke client only one engineer understands.

Look elsewhere when:

• You need streaming, server-push, or bidirectional channels → gRPC, WebSockets, or SSE.
• You need strong typing and generated clients across languages → gRPC/Protobuf, or OpenAPI-generated SDKs.
• You need auth, rate limiting, retries with backoff, circuit breaking, and tracing as product features → a gateway or a batteries-included framework layer.
• High-throughput or latency-critical paths where PHP's process model and this library's simplicity become the bottleneck.
• You require vendor-backed SLAs, a named security response owner, or a stable (non-beta) API contract.
• The API surface is large and client-driven → GraphQL is usually the better product bet.

Due-diligence flags — what this release closed and what it did not:

• Largely closed: runtime support (CI on PHP 8.4 and 8.5), test coverage and edge cases (366 tests, 100% line coverage enforced, batch and notification behavior covered, transports tested against real HTTP servers), static analysis and style gates, and the absence of a migration document (UPGRADE-2.0.md now maps every v1 call to its v2 form and lists behavior changes in full, not just the parameter-coercion change).
• Still open: community validation is unchanged — the project remains low-star, zero-dependent, with a single maintainer as the bus factor, and 2.x living on an open PR. Code quality is not adoption; do not let the quality signals launder the bus-factor risk.
• New flags: confirm the Packagist vendor name we are requiring (fguillot/json-rpc) is the one we intend relative to the source repository (matasarei/json-rpc) — a mismatched vendor/name pair is a supply-chain question worth one message, not an incident. Confirm the actual minimum PHP version against our runtime, since CI only proves the newest two. Confirm the license file still asserts MIT. Pin the exact beta and the lockfile; assume we may need to fork, and budget slightly more than a half-day now that the client transports, server, and cookie handling have grown.
• Migration flag: read UPGRADE-2.0.md in full before bumping. The parameter-coercion change is the one most likely to break an existing deployment, and it breaks silently in the sense that it presents as -32602 in production rather than as a composer error.

How to Pitch It (Stakeholders)

For executives (30 seconds): We need to integrate with partners and internal systems that speak JSON-RPC, a standard remote-call protocol. Rather than have an engineer write and maintain that protocol handling from scratch, this MIT-licensed library gives it to us for free. The newest release closed the quality question — it enforces full test coverage and strict static analysis in CI and tests its network code against real servers — which is what we would otherwise pay for. The remaining risk is not code quality, it is adoption: it is a small project with one maintainer, so we pin the version, wrap it so our code never depends on it directly, and keep the option to fork, which stays cheap at this size. One caveat worth stating plainly: the current release is a beta, so we would use it for internal work first and only adopt it broadly once 2.0 is final. Low cost, low lock-in, no bespoke protocol code.

For engineering: Adopt as the transport layer only. Wrap it in a Laravel service provider with config-driven endpoint registration and a handler registry so controllers and jobs never touch the library directly. Use Laravel's HTTP client where you need middleware, retries, or logging, and let this library handle envelope construction, error mapping, and the now-substantial transport hardening (gzip, short bodies, preserved error objects, response-id validation). Two things to settle before writing code: (1) pin the beta explicitly and treat 2.x as movable — isolate anything that depends on its API behind our facade; (2) decide our parameter-typing posture up front, because v2 no longer coerces, and a lenient client sending ["5","3"] into an int signature now gets -32602. Prefer strict, versioned contracts; if we cannot, either stay on 1.x for that surface or absorb coercion in our own handler layer. Write contract tests against the specific peers we care about, especially batch aggregation, error codes, and the new strict-params behavior — the library's tests validate the library, not our partners. Budget: ~1–3 days of glue plus a spike to validate one real endpoint end-to-end, plus a half-day to work through UPGRADE-2.0.md if we are already on v1. Success criteria: one production integration shipped in under a week with no bespoke protocol code in the codebase, and no beta-versioned library code reachable outside our wrapper. Revisit at 2.0.0 final and again in six months; if we have built the same glue twice, promote it to an internal package.