Contract Laravel Package

Technical Evaluation

Architecture fit. Release 0.9.1 materially changes the earlier read. The note — “let the stub functions answer through a runtime double” — confirms the package ships executable stub functions, not just interfaces and DTOs. That makes it a client-side stub layer for the Rapira contract, with a swappable runtime for testing. Architecturally that is legitimate, but it belongs in the adapter/infrastructure layer, never in domain or application code. The positive signal is that the maintainer has built an explicit testing seam; a package with a runtime double is easier to verify than one with only opaque stubs. The negative signal is that the package now carries runtime behavior, resolution logic, and likely a binding mechanism, all of which can leak into production if the double is selectable by configuration rather than by test-only construction.

Integration feasibility. Composer installation remains trivial. Integration now includes answering a new class of question: how are stub functions resolved, and how is the runtime double selected? If the double is activated through a container binding or a static runtime registry, test isolation and production safety both depend on that mechanism being explicit and fail-closed. If it is activated through a config flag, the integration must include a deployment assertion that the flag is off outside tests. The package is still pre-1.0 at 0.9.1, so feature releases in the 0.9.x line can carry breaking API changes.

Technical risk. The dominant risks have shifted:

• Runtime double leakage. A test double that can answer stub calls is valuable in CI and dangerous in production. If the double is autoloaded in the production build, a misconfiguration could return fabricated responses.
• Generated stub drift. “Stub functions” strongly implies generated code mirroring the Rust contract. If generation is automated, drift risk falls; if the stubs are hand-maintained, the earlier contract-drift risk is now larger because the package contains callable behavior, not just types.
• Hidden transport and container coupling. Stub resolution may register a service provider, facade, or static registry. Each of those changes the integration surface and must be inspected before adoption.
• Pre-1.0 API surface. 0.9.1 is a feature release in a pre-1.0 line. Treat the stub API as unstable.
• Bus factor and provenance. Unchanged: single maintainer, near-zero adoption, and no evidence of Laravel consumers. We remain the first serious integrator.
• Future-dated metadata. Still unresolved; verify against git tags, not Packagist dates.

Key questions to resolve before adoption.

1. Are the stub functions generated from the Rust definitions, and if so, what is the generation command and cadence?
2. How is the runtime double selected — container binding, static registry, config flag, or constructor injection?
3. Does the double ship in the production autoload path, or is it excluded from the production package?
4. Does the package register a service provider, facade, or global helper?
5. What is the transport contract — HTTP/JSON, gRPC, or something else — and is it documented?
6. What are the declared php and illuminate/* constraints, and is there a test suite covering the double?
7. Is there a fail-closed mechanism preventing the double from being used outside the test environment?

Integration Approach

Stack fit. The package now fits as an adapter-layer dependency with a testing facility. It should be required in production only if the stubs are used by the adapter; the runtime double should be treated as test infrastructure even if it ships in the same package. Verify PSR-4 namespace, auto-discovery, and whether the double is namespaced under a Testing or Double sub-namespace that can be excluded or guarded.

Migration path. The earlier isolation advice is now mandatory rather than advisory:

1. Adapter isolation. Wrap all stub calls behind our own port interfaces. Domain and application layers must not reference Rapira\Contract\* or any stub function directly.
2. Explicit mapping. Keep mapper classes between vendor payloads and domain objects so that a breaking stub change is absorbed in one directory.
3. Double discipline. Use the runtime double only in tests. Add a CI/deployment check that asserts the double is not active in staging or production. Prefer constructor injection of the runtime over static or container-global selection.
4. Version pinning. Pin to an exact 0.9.1 until at least one 0.9.x cycle has been observed, and re-verify the stub API at each bump.
5. Fork/mirror. Maintain an internal fork or VCS path repository as an escape hatch.

Compatibility. Check composer why-not against our PHP and Laravel versions. If the package declares no illuminate/* constraints, that is good for compatibility but weak evidence of Laravel testing. Confirm the generated stubs do not require a PHP extension or a specific runtime version beyond our platform. Confirm the runtime double does not introduce a dev-only dependency into the production autoload graph.

Sequencing. Two sprints remains appropriate, with sharper acceptance criteria:

• Sprint 1: Spike. Inspect the stub generation path, the double activation mechanism, and the service-provider surface. Produce a findings memo with a go/no-go recommendation. The critical question is whether the double can be made fail-closed in production.
• Sprint 2: If go, build the adapter layer and a contract test suite that uses the runtime double for fast tests and a live Rapira instance for round-trip serialization tests. Add a production guard test asserting the double is disabled outside the test environment.

Operational Impact

Maintenance. The package now has a generation surface. Budget recurring effort to regenerate or verify stubs whenever the Rust contract changes, and to re-run the contract test suite on each Laravel upgrade. The adapter layer keeps that cost bounded, but the generation step is a new operational task that did not exist under the contracts-only assumption.

Support. Support remains direct-to-maintainer. Establish a human contact in the Rapira org and confirm whether issues and PRs are triaged. With a runtime double now in the package, support questions are likely to include test-double behavior, which makes upstream responsiveness more valuable than before.

Scaling. Stub functions imply serialization and transport boundaries. Test-double performance is irrelevant at scale, but production stub overhead is not. Benchmark the PHP-side serialization path against expected payload volumes, especially if the Rust side is highly optimized. Organizationally, the risk is that multiple teams adopt the stubs independently and diverge in how they configure the runtime; central ownership of the adapter and the double guard is the mitigation.

Failure modes.

Ramp-up. The package itself remains sub-hour onboarding for a Laravel team. The new learning curve is the stub and double mechanism: how stubs are generated, how the double is selected, and how to keep the two separated across environments. Estimate one engineer-week to independent contribution, most of it spent on the Rapira contract semantics and the generation workflow rather than on Laravel integration. Document the double guard and the generation command in the repository; those two documents are the onboarding artifacts that matter.

Recommendation. Conditionally viable, with a higher bar than before. Release 0.9.1 resolves the “is it contracts-only?” question in the negative: it is a stub layer with a runtime double. That is workable if the double can be made fail-closed and the stubs are generated from the Rust source of truth. If either condition cannot be demonstrated in the Sprint 1 spike, define the boundary types internally and use this package as reference material rather than a dependency. The testing seam is a genuine positive; the production-safety question is now the deciding factor.