Contract Laravel Package

Product Decisions This Supports

• Contract-first API design between a Rapira (Rust) service and PHP consumers. The package publishes the shared type/interface vocabulary, so request and response shapes are defined once instead of hand-duplicated in every PHP client. That directly reduces integration drift and the "which side changed?" class of bugs.
• Build vs. buy is really "adopt vs. re-derive." The artifact is thin (contracts/interfaces), so the true cost of walking away is low. That makes this a reversible, tactical decision rather than a platform commitment — a key input when prioritizing it against larger architectural work.
• Roadmap: multi-language service surface. Supports a strategy where a Rust core is consumed by PHP/Laravel apps — internal admin tools, partner SDKs, or a phased monolith-to-services migration where you need typed seams rather than ad-hoc HTTP calls.
• Team boundary definition. Producer owns the contract, consumers implement against it. This decouples delivery so PHP and Rust teams can ship in parallel without an integration freeze, and gives you a named owner per side.
• Consumer-driven contract testing as a release gate. The contracts create a testable seam; you can assert in CI that the PHP side still satisfies the producer's expectations before deploy, and fail the build instead of the customer. As of 0.9.1 the stub functions can answer through a runtime double, which means PHP consumers can be tested against the contract shapes without a live Rapira service — local dev, unit tests, and CI no longer need the Rust backend standing up. This is the release that turns the testing bullet from "possible" into "cheap."
• Parallel delivery without a backend dependency. The runtime double removes a recurring scheduling tax: PHP work is no longer blocked waiting for a runnable Rust environment. That matters most in the earliest phase of a migration, when the producer side is least stable.
• Compatibility and versioning policy. Pinning a contract package version gives release planning an explicit compatibility boundary — you can reason about "this client speaks contract vX" rather than inferring it from deployed code. Note the project is still pre-1.0 (0.9.x), so minor bumps can carry behavior changes; pin exactly and read the changelog on every bump.
• Prioritization signal: still no network effects. One star, zero dependents means no ecosystem leverage. The 0.9.1 release and its PR flow are a mild positive maintenance signal, but not enough to reframe this as an ecosystem bet. Adopt it as an internal architecture choice with a named maintainer, and don't let a dependency scan imply you've gained community support you haven't.

When to Consider This Package

Consider it when:

• You already run, or have a funded plan to run, a Rapira-based backend and need PHP consumers typed against it.
• You want a dependency-light contract layer rather than a full framework or a heavyweight codegen pipeline.
• You want to test PHP consumers before the Rust service exists or is stable. The 0.9.1 runtime double lets you exercise the contract seam in isolation — a concrete reason to adopt earlier than you otherwise would in a phased migration.
• Your team can read the entire source in an afternoon and is willing to own it.
• You can pin it exactly (composer require with a fixed constraint plus a committed lockfile) and vendor or fork it if upstream stalls. Confirm the license permits forking before you commit. Treat pre-1.0 minor releases as potentially behavior-changing and review each one.

Look elsewhere when:

• You need Laravel-native ergonomics — form requests, validation rules, framework-integrated resolution — or first-class Symfony support. This package is not that, and adapting it may cost more than it saves.
• You need vendor support, SLAs, security review evidence, or a dependency acceptable in a regulated environment. With this adoption profile, that evidence does not exist.
• A standards-based IDL (OpenAPI, JSON Schema, Protobuf) would give you the same contract guarantee with far more tooling, multi-language codegen, and hiring familiarity. For most teams this is the stronger default. Note that the new runtime double narrows this gap only for the testing concern, not for codegen or multi-language reach.
• The Rust service is still speculative. Don't pay integration cost for a boundary that may never ship.
• You require more than roughly two consuming languages. At that point hand-maintained PHP contracts stop scaling and an IDL pays for itself.

How to Pitch It (Stakeholders)

For executives: This is a very small PHP package that publishes shared contract definitions for services built on Rapira. The business case is narrow but real: it stops the Rust backend and our PHP clients from quietly diverging in payload shape, which is a common source of production incidents and rework. The newest release (0.9.1) adds a test double so PHP teams can build and test against the contract without waiting on a running Rust service — that removes a scheduling dependency and makes the CI safety net cheap to stand up. Adoption cost is near zero and the decision is reversible — the artifact is thin enough to vendor or replace in days, not quarters. The material risk remains maturity: one star and zero known dependents means no community, no vendor, no support path, and the project is still pre-1.0. So treat it as internal code we own from day one, not a third-party dependency we lean on. Recommendation: green-light as a tactical tool inside a single service boundary, assign a named owner, pin the version exactly, and set an explicit review trigger — re-evaluate if upstream goes unmaintained for six months, or if we add a third language consumer, at which point we move to an OpenAPI or Protobuf IDL.

For engineering: Typed seams, one source of truth for payload shapes, and a natural place to hang contract tests in CI — now runnable locally via the 0.9.1 runtime double, so no Rapira service required in dev or test. Costs: a pinned dependency (pre-1.0, so check each minor bump), a documented fork/vendor fallback, and a small standing owner. Expect an afternoon to evaluate and integrate; size the ongoing cost honestly rather than assuming upstream will absorb it.

Decision framing: Approve as a tactical, single-boundary tool. The 0.9.1 runtime double strengthens the testing story and lowers the cost of adoption but does not change the strategic picture. Do not present it as a strategic platform bet, and do not let it become load-bearing for multiple teams without an explicit re-evaluation.