Tomato Contracts Laravel Package

Product Decisions This Supports

• Ecosystem alignment / build-vs-buy. tomato-contracts is a contracts-only package (PHP interfaces and abstract definitions) rather than a feature package. Its product value is not user-facing functionality — it is the shared vocabulary that lets TomatoPHP modules, plugins, and third-party extensions interoperate. Adopting it is a bet on the TomatoPHP ecosystem as your integration substrate, not a bet on a feature.
• Plugin and extension architecture decisions. If your roadmap includes letting internal teams or external partners extend your admin/CMS surface (custom panels, custom resource types, custom auth flows), a contracts package is the seam that makes that possible without forking vendor code. This directly informs whether you build a bespoke extension layer or lean on the vendor's interface definitions.
• Lock-in and exit-cost modelling. Contracts defined in a dedicated, low-churn package are the cheapest thing to keep when you eventually swap implementations. Including it in your dependency graph is a hedge: it isolates what you depend on from who implements it, which affects how aggressive you can be in a later re-platforming decision.
• Upgrade-cost forecasting for the roadmap. Because the package ships independently of implementations, breaking changes here propagate further and faster than breaking changes in any single feature package. Its version cadence is therefore a leading indicator for how much upgrade budget to reserve across the whole TomatoPHP surface each quarter.
• Release-train sequencing. If you ship on top of TomatoPHP, this package's minor/patch cadence constrains when you can safely cut your own releases. It belongs in your dependency-pinning policy discussion, not your feature backlog.
• Vendor consolidation. If you are currently maintaining hand-rolled interfaces that duplicate these, this is the trigger to evaluate deletion of bespoke glue code — a concrete maintenance-cost reduction to weigh against coupling to a single maintainer.

When to Consider This Package

Consider it when:

• You are already standardising on the TomatoPHP stack and want extension points that survive vendor upgrades rather than forking.
• You are writing a plugin, module, or integration that must plug into more than one TomatoPHP-based application and needs a stable, shared type surface.
• You maintain internal packages that duplicate vendor interfaces, and you want to depend on contracts instead of on concrete implementations.
• You are evaluating the TomatoPHP ecosystem as a whole and want to gauge its architectural maturity — a dedicated contracts package is a positive signal of intent, even at v0.0.1.
• You need a defensible answer to "what exactly would it cost us to leave?" — contracts make that answer measurable.

Look elsewhere when:

• You need production guarantees today. v0.0.1 is a pre-1.0 initial release with no migration path and, on the evidence available, no published changelog detail beyond a commit link. Anything at 0.0.x should be treated as an unstable API: expect renames and removals without deprecation cycles.
• You are not on TomatoPHP. Contracts are only meaningful against implementations that consume them; standing alone the package delivers no runtime behaviour.
• You are subject to procurement/security review that requires release notes, a published support policy, or a security disclosure process. None of that is evidenced here yet.
• Your organisation cannot accept a single-maintainer dependency for a package that sits underneath your extension architecture. This is a structural dependency, so assess maintainer bus-factor and fork-ability before adoption, not after.
• You need framework-level abstraction. Laravel's own container bindings and PHP interfaces may already cover your needs; adding a vendor contracts layer on top of an already-small surface is pure overhead.
• You need it stable now for a shipped product. Pin nothing here until you see a 0.1.x with an actual changelog and at least one dependent package declaring a version constraint against it.

How to Pitch It (Stakeholders)

To executives: This is a small, low-risk architectural dependency, not a feature investment. It costs essentially nothing to evaluate and gives us a defined interface boundary between our code and the vendor's — which is the thing that makes a future migration cheaper and a future integration faster. The honest caveat is maturity: it is a v0.0.1 initial release with no published changelog, so we should treat the API as unstable and avoid building load-bearing production code on it this quarter. Recommendation: approve a time-boxed spike, not a commitment.

To engineering: Treat this as the shared type surface for the TomatoPHP modules we already use. It lets us write extensions against interfaces instead of concrete classes, which means vendor upgrades touch fewer of our files and our own packages stop carrying duplicate interface definitions. Practical guidance: pin exactly, expect breaking renames before 0.1.0, wrap any usage behind our own adapter so a swap is a one-file change, and do not let it become a transitive dependency of anything customer-facing until we see a real changelog and a stable tag. If we do not get a documented release history by the next review, that is the signal to keep our own interfaces and revisit later.

To the wider business (one line): We are adopting a stable vocabulary for our integrations, deliberately kept at arm's length until the vendor demonstrates release discipline.