Download the PHP package aicrion/json-rpc without Composer

Aicrion\JsonRpc

A modern, attribute-driven JSON-RPC 2.0 server library for PHP 8.2+.

Full documentation (installation, every feature, API reference) lives in docs/index.md -- built to be published on GitHub Pages. This README is a concise overview and quick-start reference.

Architecture

Unlike classic dispatcher-style RPC libraries, this library is built as a pipeline of independent stages, similar in spirit to HTTP middleware stacks. Every request flows through the same fixed sequence:

Every stage implements the same Pipeline\Stage interface, so the pipeline can be extended (via withMiddleware()) without ever touching the kernel's internals.

Requirements

• PHP >= 8.2
• psr/container (installed automatically as a dependency; only required at runtime if you use ContainerHandlerFactory)

Installation

Running tests

Run a single test:

Quick start

Feature overview

Namespaced handlers

Every handler declares its own namespace via #[RpcHandler('math')], #[RpcHandler('account')], etc. Methods become reachable as math.add, account.balance, and any number of handlers/namespaces can be registered on the same kernel without colliding (a duplicate qualified name throws at build time).

Automatic protected methods

Instead of guarding each method by hand, annotate the whole handler class:

The registry resolves protection once, at registration time, so AuthorizationStage never needs per-method wiring. The actual yes/no decision is delegated to any AuthorizationGate you provide via withAuthorizationGate() (defaults to fail-closed, denying every protected method).

Auto-discovery and lazy loading

No handler is ever instantiated until one of its methods is actually invoked -- regardless of which registration strategy you use:

Two ways to avoid the cost of scanning a directory on every request:

• Cache the scan to disk: pass a cacheFile to withDiscoveredHandlers(). The directory is scanned once, the resulting class list is persisted, and every subsequent build() skips the filesystem walk entirely.
• Resolve on demand, never scan: use withResolvedHandlers() with a NamespaceResolver (ConventionNamespaceResolver or MapNamespaceResolver). The handler class for a namespace is computed purely from a naming convention or explicit map, and verified via class_exists() the first time that namespace is actually requested.

Handlers needing constructor dependencies can be built through any PSR-11 container via ContainerHandlerFactory, passed to any of the lazy registration methods above.

Batch requests (JSON-RPC 2.0 spec compliant)

dispatchJson() auto-detects whether the raw body is a single request object or a batch array and responds accordingly.

Custom middleware stages

Plug any Stage implementation into the pipeline, right after authorization and before parameter binding:

Invocation listeners

Observe every call without touching the pipeline:

Listeners fire around InvokeHandlerStage only -- a cache hit never triggers them, since the real handler method was never called.

Caching with pluggable backends

Annotate any method with #[Cacheable] to memoize its result. Pick any CacheStore implementation that fits your deployment:

Cache keys are derived from the method name and bound arguments via CacheKeyBuilder (default: DefaultCacheKeyBuilder), also swappable with withCacheKeyBuilder().

Rate limiting, local or distributed

RateLimitStage depends on the RateLimitStore abstraction, so the exact same middleware works identically on one server or across a cluster:

Returning custom errors from a handler

Throwing a plain exception inside a handler is always wrapped into a generic -32000 error, protecting clients from internal stack traces. To return a specific code/message/data for an expected business failure, throw Exception\RpcErrorException instead:

This propagates untouched to the client, while any other, unexpected exception still gets wrapped as a generic internal error. Reserve custom codes below -32000 to avoid colliding with the JSON-RPC 2.0 reserved range and this library's own codes (-32001 unauthorized, -32002 rate limited).

Error codes

Documentation and license

See docs/index.md for the full guide, including a complete API reference. Published under the MIT License.

📜 License

Created with ❤️ by Aicrion. Licensed under the MIT License. Free to use, modify, and distribute!