Jsonrpc Server Doc Sdk Laravel Package

Getting Started

What this package actually is. yoanm/jsonrpc-server-doc-sdk is a domain model only — a set of plain PHP objects (ServerDoc, MethodDoc, TagDoc, ErrorDoc, HttpServerDoc, and a Type\* family for params/results). It contains no HTTP layer, no serializer, and no Symfony bundle. You populate the graph, then serialize it yourself. Understanding that boundary in the first ten minutes saves a lot of confusion.

Minimal steps:

1. composer require yoanm/jsonrpc-server-doc-sdk symfony/serializer (the serializer is not pulled in for you; you need it to produce JSON).
2. Open src/Domain/Model/ in the vendor directory first. The whole package is small; the model classes are the documentation of the documentation format. Read ServerDoc, MethodDoc, and Type/ in that order.
3. Build one doc object by hand in a scratch script and dump it through the serializer. You will see the exact JSON contract your consumers will render against.
4. Wire a single read-only endpoint (or a JSON-RPC rpc.discover-style method) that returns that JSON.

First use case to ship: one method, documented end to end — a MethodDoc with a name, description, one tag, an ObjectDoc params type with two scalar children, and the error codes the method can return. Once that round-trips through the serializer into shape your frontend/tooling expects, the rest is repetition.

$doc = (new ServerDoc())
    ->setName('Billing API')
    ->setVersion('1.4.0');

$method = (new MethodDoc())
    ->setName('invoice.create')
    ->setDescription('Creates an invoice')
    ->addTag(new TagDoc('billing'));

$params = new ObjectDoc();
$params->addChild('customerId', new StringDoc());
$method->setParamsDoc($params);
$doc->addMethodDoc($method);

(Exact setter names vary by version — let IDE autocomplete on the model classes guide you rather than docs on the web, which are thin.)

Implementation Patterns

Derive docs from the same source as your method registry. The single biggest day-to-day win is eliminating drift: iterate whatever collection you already use to register JsonRpcMethodInterface services (a tagged-iterator in Symfony, a registry class otherwise) and emit one MethodDoc per entry. If a method exists but has no MethodDoc, fail a unit test — not a code review.

Two-layer doc building. Separate static metadata (names, tags, descriptions, error codes, param schemas — authored in attributes or YAML next to the method) from dynamic metadata (examples, deprecation notices, version strings read from composer.json or a build constant). Compose both into the ServerDoc in a single DocBuilder service. This keeps the builder deterministic and cacheable, and stops environment-specific values leaking into committed config.

Cache the serialized output, not the model. Building the graph is cheap; serializing and re-normalizing on every request is not. Serialize once into a PSR-6/PSR-16 cache or a build artifact written at container-warmup time, keyed by a hash of the doc source files. Invalidate on deploy. For small APIs just warm it in a composer/dev script and commit the snapshot for tests.

Serve it two ways. Expose the JSON at a plain GET /api/doc (behind auth or non-prod gating if your API surface is sensitive) and as a JSON-RPC method if your consumers only speak JSON-RPC. Both should read from the same cached payload so they cannot disagree.

Test with snapshots plus coverage assertions. One test asserts the serialized JSON matches an approved snapshot (catches accidental format breakage for frontend consumers). A second asserts every registered server method has a corresponding MethodDoc and vice versa — this is the assertion that actually earns its keep over months.

Integration tip: parameter Type\* docs describe; they do not validate. Keep them aligned with your real request validator (in the yoanm/php-jsonrpc-server-sdk stack, the params validator) by generating both from one schema definition, or by adding a test that walks the validator's rules and compares them to the TypeDoc tree.

Gotchas and Tips

• No serializer is bundled. You must pick the strategy (Symfony Serializer with normalizers/attributes, or hand-rolled JsonSerializable). Output shape — null fields, key ordering, empty collections — is entirely your serializer config. Pin it in a test, because a serializer upgrade can silently change your public doc contract.
• Duplicated error-code truth. ErrorDoc codes must mirror what the server actually throws. Define error codes once (a constants class/enum) and feed both the doc builder and the error handler. Two hand-maintained lists will diverge within a sprint.
• The model is mutable. Treat the built ServerDoc as immutable after construction. Do not mutate a shared, cached graph per request — clone or rebuild instead. This is an easy footgun in long-running workers (RoadRunner/Swoole) where a service instance survives across requests.
• HttpServerDoc is only relevant over HTTP. If you serve JSON-RPC over HTTP, its link/route info must be kept in sync with actual routing; if you are transport-agnostic, skip it rather than lying.
• Not OpenAPI. No Swagger UI, no generated clients, no Postman import. Consumers need a custom renderer, or you write a small adapter that maps the model onto OpenAPI for tooling. Budget for that; it is usually the real cost of adopting this package.
• Small ecosystem (zero dependents, low opportunity score). Pin to an exact minor version in composer.json, read the changelog on every bump, and avoid extending the model classes unless you have verified they are not final. Prefer wrapping (DocBuilder decorators) over subclassing.
• Debugging: when the JSON looks wrong, var_dump the object graph before serialization — it is nearly always an unset/misnamed child on a TypeDoc or a missed add* call, not a serializer bug. A one-line json_encode-style dump of the model tree with print_r is the fastest loop.
• Extension points: custom normalizers are the cleanest way to inject vendor-specific fields (owner team, SLA, internal links) without fighting the model. The second cleanest is a decorator around your DocBuilder that post-processes the array after serialization.
• Check composer.json PHP constraint before adopting — it tracks recent PHP versions and may block you on older runtimes.