Openrpc Laravel Package

Technical Evaluation

Architecture fit. psx/openrpc is a set of plain PHP model classes that serialize to an OpenRPC document — a JSON-RPC API description format, not OpenAPI/REST. It is part of the Apioo/PSX ecosystem and is deliberately framework-agnostic: it carries no Laravel service provider, config, facade, or contract. That is architecturally clean for a spec-generation use case (it is a build-time data model, not a runtime concern), but it means Laravel will treat it as an inert Composer dependency. There is no auto-discovery of your routes, controllers, or JSON-RPC handlers — you build the introspection layer yourself.

Integration feasibility. Low friction to install (composer require psx/openrpc), moderate-to-high effort to make useful. The package gives you the vocabulary (Method, ContentDescriptor, Error, Server, Components, Reference, etc.) type-safely; it does not give you a generator. A TPM should budget for a custom artisan command plus a mapping layer from your JSON-RPC method registry into these model objects, and a serializer step to emit the final JSON. Whether the models ship with a serializer (PSX typically uses psx/model or psx/schema for this) must be verified on day one — that transitive coupling is the crux of the risk.

Technical risk.

• Adoption risk (high). 3 stars, 0 dependents, single-maintainer project. Treat as effectively unmaintained until proven otherwise; check commit recency, open-issue latency, and last tagged release.
• Ecosystem coupling (medium-high). Likely pulls psx/model / psx/schema and PSX conventions that may conflict with modern Laravel dependency constraints (PSR interfaces, PHPUnit majors). Run composer why psx/model in a throwaway branch before committing.
• Spec-version risk (medium). OpenRPC has evolved (1.0 → 1.2.x). Confirm the package targets the version your client tooling expects; an older model set may omit components, examples, or content-descriptor schemas.
• Tooling asymmetry (medium). OpenRPC client generators are far thinner than OpenAPI's. Confirm your consuming teams actually use JSON-RPC and have codegen/validation tooling.
• License risk (low). Apache-2.0 is permissive; a hard fork is legally straightforward if needed.

Key questions.

1. Which OpenRPC spec version is modeled, and does it cover components, errors, examples, and $ref?
2. Is serialization bundled, or must we add psx/model/psx/schema? What PHP versions are supported?
3. Is our API surface actually JSON-RPC, or REST? (If REST, this is the wrong primitive — stop here.)
4. Do we have an existing method registry to introspect, or would we also be building a registry?
5. What is the maintenance signal — commits in the last 12 months, tagged releases, CI status?

Integration Approach

Stack fit. Treat this as a dev/CI-only dependency (composer require --dev psx/openrpc). Spec generation is a release artifact, not a request-path concern; keeping it out of production autoload avoids polluting the runtime container and sidesteps any transitive-dependency conflicts with runtime packages. It fits Laravel 10/11/12 provided the transitive PSX deps allow PHP 8.1+; verify first.

Migration path. There is no incumbent to migrate from unless you are hand-maintaining a JSON spec, in which case the path is:

1. Spike (1–2 days). Stand up a scratch Laravel command that instantiates three models (Server, Method, ContentDescriptor), serializes, and validates the output against the OpenRPC JSON Schema. This single spike de-risks 80% of the decision.
2. Wrapper. If the spike passes, wrap construction in an internal App\OpenRpc\SpecBuilder so the vendor package is only referenced in one namespace. This is the key hedge: it makes a future fork or replacement a one-file change.
3. Generator. Write php artisan rpc:spec that walks your JSON-RPC method registry and emits openrpc.json to a build path.
4. Publish. Commit the artifact to a docs site or attach it to the release, not to the application runtime.

Compatibility. The real compatibility question is not Laravel — it is consumer compatibility. Validate emitted documents with an independent JSON-Schema validator, not just the package's own serialization, so you catch spec-version drift. Also confirm the package's PHP constraint matches your CI matrix; PSX packages have historically lagged new PHP majors.

Sequencing. Spike → wrapper → generator → CI drift gate → publish. Do not start with the generator; start by proving the serializer and validator loop works, because the package's value proposition collapses if serialization is incomplete or schema-invalid. Gate the whole initiative on the spike result and a documented fallback: hand-rolled arrays + justinrainbow/json-schema validation is a viable plan B at roughly the same effort, without the maintenance exposure.

Operational Impact

Maintenance. This is the dominant operational cost. Single maintainer, near-zero community, and 0 dependents means no collective bug-fixing pressure. Pin an exact version in composer.json, document why the pin exists, and pre-authorize a fork under Apache-2.0. Budget a nominal recurring cost (~1–2 days/quarter) for version review and spec-version tracking; this is small but must be named in the roadmap, not discovered later.

Support. Expect no external support. The support model is "read the PSX source" — the models are small and legible, which helps, but there are no examples, no docs, and no Stack Overflow trail. Internal ownership must be assigned to a named engineer.

Scaling. Operationally a non-issue: pure data classes, no I/O, generation is O(number of methods) and runs at build time. It will never be a throughput or memory factor. The scaling concern is organizational — as the API surface grows, the custom introspection layer grows with it and becomes the real maintenance burden, not the vendor package.

Failure modes.

• Silent spec drift. Routes/methods change, the artifact does not regenerate → stale docs, broken clients. Mitigate with a CI check that regenerates and fails on a non-empty git diff.
• Dependency conflict. A routine composer update in the main app pulls a transitive PSR/PHPUnit version that clamps the PSX tree. Isolating to --dev and pinning contains the blast radius.
• Invalid output. Serializer emits a document that violates the target OpenRPC schema version. Mitigate with schema validation in CI, not just unit assertions.
• Abandonment cliff. Maintainer stops tagging; a new PHP major breaks the models. The wrapper namespace makes the fork/replace decision cheap.

Ramp-up. A mid-level Laravel engineer needs roughly 1–2 days to read the OpenRPC spec and the PSX model conventions, plus 2–4 days to build and test the generator and CI gate. The learning cost is front-loaded and does not compound — the models are declarative and shallow. The honest TPM framing: this package supplies a small, well-typed convenience over a niche spec format, at the price of a single-maintainer dependency. It is reasonable as an isolated, pinned, dev-only dependency behind an internal wrapper; it is not reasonable as a strategic or widely-shared one.