Server Laravel Package

Technical Evaluation

Architecture fit Sajya (sajya/server) implements a JSON-RPC 2.0 server endpoint for Laravel: a single POST route that dispatches to registered "procedure" classes, with framework-native parameter binding, validation, structured error objects, batch requests, and notifications. Architecturally it is an edge/transport layer, not a domain library — it sits alongside (not inside) your application services, resolving procedures through the Laravel container and running them through the normal middleware stack.

For a TPM this means the decision is a contract-style decision, not a dependency decision. JSON-RPC buys you method-oriented dispatch, a uniform error envelope, and batching on one endpoint; it costs you HTTP semantics (caching, per-resource status codes, standard OpenAPI tooling) and consumer familiarity. It is a good fit for internal service-to-service calls, partner integrations with a fixed method catalogue, or exposing an existing application-service layer to a non-HTTP-idiomatic client. It is a poor fit as the primary public API for browser/mobile consumers where REST or GraphQL tooling and gateway policy (per-route authz, CDN caching, schema linting) are expected.

Integration feasibility Low. composer require sajya/server, publish the config, define procedure classes, register them in the config map, and expose the endpoint under a chosen middleware group. No database, queue, or infrastructure dependency. A working pilot is a one-to-two-day exercise for a Laravel developer, which makes this cheap to evaluate and cheap to reverse.

Two items in 7.1.0 materially affect feasibility:

• Laravel 13.x compatibility (#84) — contributed by laravel-shift, i.e. automated framework-compat tooling rather than a hand-authored change. This is a positive signal for the package's longevity but should be treated as declared compatibility, not verified compatibility, until your own CI matrix has run it. It also implies the package intends to track Laravel releases, which de-risks the medium term.
• Attribute retrieval switched to IS_INSTANCEOF (#87) — a behavioural change in reflection-based attribute resolution, not a cosmetic one. Where the package previously matched attributes by exact class, it now matches subclasses. If any of your procedures use custom attributes that extend the package's own, the set of attributes applied to a procedure can grow after this upgrade. Conversely, if you were working around the old exact-match behaviour, that workaround may now double-apply. This is the only line in the release that can change runtime behaviour, and it is the one to write a regression test for.

The remaining six entries are Dependabot bumps to GitHub Actions (checkout, cache, git-auto-commit-action). They affect the maintainer's CI pipeline only, carry zero runtime surface, and should be recorded as such rather than reviewed as functional changes.

Technical risk Overall: low-to-moderate, concentrated in two places.

• Behavioural risk (medium-low): the IS_INSTANCEOF change. Bounded and testable, but silent if untested — attribute-driven behaviour failures tend to surface as "wrong validation applied" or "procedure not registered," not as exceptions.
• Supply-chain / maintenance risk (medium): small-maintainer package, no commercial backing, no vendor SLA. laravel-shift automation covering framework bumps reduces the risk of abandonment but also means the compatibility PR may have had lighter human review than a hand-written port.
• Lock-in risk (low): the package is thin. Procedures are ordinary classes; if you ever need to leave, you can re-implement the dispatch layer against your own controller in days. This is the strongest argument for the dependency.
• Contract risk (medium, non-technical): JSON-RPC contracts are rarely schema-governed. Without a discipline of versioned method names and documented error codes, the method catalogue drifts and becomes an un-auditable public surface.

Key questions

1. Which Laravel versions are actually in production, and does the package's composer.json constraint genuinely permit all of them — or does 7.1.0 require a floor that forces a framework upgrade first?
2. What PHP floor does 7.1.0 impose, and does it match our runtime images?
3. Do we have any custom attributes extending the package's attributes today? If yes, #87 is a required regression test; if no, it is a no-op.
4. Does the consuming client actually want JSON-RPC semantics (batching, notifications, method dispatch), or are we choosing it for developer convenience on the server side only?
5. Who owns the method catalogue and error-code registry internally, and where is it documented?
6. Is there a policy for batch size limits and per-method rate limiting, or does the endpoint inherit only the default route middleware?
7. Is the package's release cadence sufficient for our patch SLA, or do we need a fork-and-vendor contingency?

Integration Approach

Stack fit Standard Laravel HTTP stack — no new runtime, no new infrastructure. The endpoint registers as a route, so it composes with existing auth guards (Sanctum/Passport/session), middleware groups, throttling, CORS, and logging without modification. Procedure classes resolve through the service container, so existing application services and repositories are reused rather than duplicated. The main fit constraint is organisational: the endpoint bypasses per-route authorisation conventions, so authorisation must be enforced inside procedures or via a shared middleware, and that discipline has to be established up front, not retrofitted.

Migration path Because there is no prior assessment, treat this as a greenfield adoption rather than an upgrade:

1. Pilot — one low-risk, read-only procedure behind the existing auth guard, in a non-production environment, so the dispatch/validation/error-envelope behaviour is observed end to end.
2. Parallel run — expose the pilot procedure to a single internal consumer alongside the equivalent REST path. Do not migrate consumers until the error envelope has been validated against their client library.
3. Hardening — authz inside procedures, batch-size cap, throttle policy, structured logging of method name + request id + error code.
4. Breadth — migrate method-by-method, keeping the REST path live until each consumer has cut over.

For teams already on 7.0.0: the upgrade to 7.1.0 is a minor bump, but run the attribute regression suite before merging. There is no data migration and no config-schema change indicated.

Compatibility Confirm by inspection of composer.json rather than by release note: the declared Laravel range, the PHP floor, and whether any transitive constraints conflict with our other packages. laravel-shift compatibility PRs are typically mechanical (constraint widening plus test-matrix updates), so verify that the CI matrix in the repository actually exercises the versions we run — a widened constraint without a corresponding matrix entry is an untested claim.

Sequencing Adopt the dependency early but the contract late. Adding the package is reversible in a day; publishing a method catalogue to external consumers is not. Sequence: dependency → pilot → internal consumers → external consumers. Gate the final step on the method catalogue and error-code registry being written down.

Operational Impact

Maintenance Low ongoing effort, but with a single-maintainer concentration risk that should be recorded in the risk register rather than assumed away. Budget roughly a half-day per Laravel major upgrade to validate compatibility and a few hours per minor release to review behavioural changes like #87. Most releases, as here, will be CI-only and require no action beyond a changelog note.

Support Community-only: GitHub issues, no vendor SLA, no paid support tier. Internal ownership must therefore be explicit — a named team accountable for the endpoint, the method catalogue, and upgrade validation. Do not adopt this package into a codebase without a team willing to own it.

Scaling The endpoint is stateless HTTP and scales exactly like any other Laravel route; no new scaling dimension is introduced. Two package-specific considerations: batch requests amplify a single HTTP call into N procedure invocations, so an uncapped batch is a cheap amplification vector — cap batch size at the middleware or config level; and notifications (requests without an id) produce no response body, which can confuse load balancers, proxies, and client timeouts if not handled deliberately.

Failure modes

• Attribute resolution drift — post-#87, custom attributes extending package attributes may apply where they previously did not (or vice versa); symptom is misapplied validation or unregistered procedures, with no exception raised.
• Error-envelope / HTTP-status mismatch — JSON-RPC carries errors in the body, often with a 200 status. Gateways, retry policies, and alerting keyed on HTTP status will see these as successes. Alerting must key on the RPC error code, not the status.
• Unhandled exception leakage — verify that non-RPC exceptions are converted to the standard error object rather than emitting a Laravel debug page or stack trace to the consumer.
• Batch partial failure — a batch can succeed for some members and fail for others; consumers must handle per-element errors, and this must be tested explicitly with the client team.
• Constraint drift — a widened Laravel constraint combined with our own pinned framework can produce a satisfiability failure at composer update; pin the package to ^7.1 and let CI prove the combination.

Ramp-up Server-side: a Laravel developer is productive in one to two days — the concepts (procedure classes, parameter binding, error codes) are small, but the JSON-RPC 2.0 specification details (notifications, batch semantics, reserved error codes) are where mistakes happen. Client-side: budget comparable effort per consuming team, since the RPC client, retry policy, and per-element batch error handling are all consumer responsibilities. Documentation effort should be weighted toward the method catalogue and error-code registry, not toward the package API.