Contracts Laravel Package

Technical Evaluation

Architecture fit. dragon-code/contracts is a pure interface package — a curated set of PHP interfaces (plus a few constants/traits-adjacent contracts) for caching (Cache\Store, Cache\Ttl), queues (Queue\ShouldQueue, ShouldBeUnique), DTOs (Dtoable), HTTP (Http\Builder), actions, and migrations. Architecturally it fits any codebase that wants dependency inversion without owning interface definitions: it adds no service provider logic, no runtime behavior, no bootstrapping, and no storage. That makes it a low-ceremony way to standardize boundaries across internal packages. The fit is strongest for teams already building reusable Laravel modules or adopting hexagonal/DDD layering where domain code must not reference framework concretes. It is a weak fit as a public API contract for external consumers, since the upstream is archived and has no dependents to validate stability.

Integration feasibility. Integration is a single composer require dragon-code/contracts, then implementing the interfaces on existing classes (or type-hinting against them in constructors). Releases show a track record of Laravel 11/12 and Symfony 6/7 alignment, which maps to modern Laravel floors. Because the package is interfaces only, rollback is trivial: remove the implements clauses and the dependency. The real integration cost is not mechanical but social — convincing teams to type against DragonCode\Contracts\... rather than framework or in-house interfaces, and enforcing that in code review/static analysis.

Technical risk. The dominant risk is lifecycle, not code: the repository is archived, has 0 dependents, 10 stars, and a single-maintainer history. Archived means no security patches, no new Laravel/PHP compatibility releases, and no upstream fixes if an interface is found to be mis-shaped. The "last release 2026-03-17" signal conflicts with the archived flag and should be reconciled before any decision — it may indicate archival occurred after a final maintenance release, or that metadata is stale. Secondary risks: interface signatures are a compatibility surface (a changed method signature or added method is a breaking change for implementers), and the package has a history of frequent minor releases adding methods (rememberForever, doesntHave, ShouldQueue, Dtoable) — benign as additions, but it shows the surface is still moving. MIT license means we can fork or vendor, which materially caps the risk. The code itself is low-risk: interfaces have no runtime failure modes and no transitive blast radius beyond Composer resolution.

Key questions. (1) Why was the project archived, and is that decision reversible or transferable? (2) Which specific interfaces do we actually need — is the value concentrated in 3–4 contracts we could re-declare in-house in an afternoon? (3) What is the PHP/Symfony floor, and does it constrain our upgrade path to Laravel 13+? (4) Who owns the fork/vendor if we adopt and upstream goes stale? (5) Does any internal package already depend on dragon-code/helpers in a way that makes these contracts a mandatory (rather than optional) dependency? (6) Is the release date metadata accurate?

Integration Approach

Stack fit. Best fit: Laravel 11/12 services, PHP 8.2+, teams already using DragonCode tooling (dragon-code/helpers) or building internal Composer packages. Poor fit: Laravel ≤10 estates, non-Laravel PHP frameworks, and any codebase that treats third-party interfaces as public API for external consumers.

Migration path. Treat this as an additive, reversible change, not a platform migration:

1. Inventory first. Grep the codebase for existing hand-rolled interfaces covering cache, queue, DTO, HTTP, and actions. Produce a mapping table: our interface → candidate package interface → shape mismatch.
2. Pilot in one internal package, not the monolith. Pick a module where mocking cache/queue is already painful; implement 2–3 contracts behind a feature branch.
3. Type-hint, don't inherit. Constructor-inject against the contract; keep concrete classes framework-native. Avoid implements on domain entities until the interface shape is proven.
4. Gate with static analysis. Add PHPStan/Psalm rules and a CI check that new code does not introduce duplicate contract definitions; this is where the standardization value actually accrues.
5. Vendor or pin. Given the archive, pin an exact version in composer.json and mirror the repository internally (or composer.json a path/VCS repo) so builds do not depend on a frozen GitHub project remaining available.

Compatibility. Verify Laravel/Symfony constraint resolution in a scratch project before touching production; interface packages can still impose version ceilings via require. Because the surface is interfaces, runtime compatibility is nearly free — the compatibility question is entirely Composer-level.

Sequencing. Run this as a 2–3 sprint background workstream: inventory (week 1) → pilot (week 2–3) → codify standards and CI guardrails (week 4) → optional broad rollout. Do not block roadmap work on it; the benefit is incremental and there is no forcing function.

Operational Impact

Maintenance. Near-zero runtime maintenance, but non-zero governance maintenance: someone must own the interface conventions, review new implements, and manage the pin. The archived status transfers upstream maintenance risk onto us; budget a contingency for forking (low effort — the code is interfaces) or re-declaring contracts in-house.

Support. No upstream support channel. Internal support burden is limited to onboarding and convention questions. Document the "why" in an ADR so future engineers do not treat the dependency as abandoned cruft and rip it out arbitrarily.

Scaling. Scales well technically — no runtime cost, no I/O, no state. The scaling constraint is organizational: consistency across many teams and repos requires enforcement (CI, linters, code review), otherwise contracts proliferate in parallel and the standardization value evaporates.

Failure modes. (1) Abandonment — a future PHP/Laravel major is incompatible and no upstream fix arrives; mitigations: fork, vendor, or re-declare. (2) Interface drift — our implementations diverge from the contract's intent, producing subtle behavioral differences across modules. (3) Over-adoption — implementing every contract because it exists, adding abstraction with no consumer. (4) Single-source build risk — depending on a frozen GitHub repo; mitigate with mirroring. (5) False standardization — teams adopt the package but keep their own interfaces, yielding two competing vocabularies.

Ramp-up. Low for individual engineers (implementing an interface is familiar Laravel work), moderate for the organization (teaching when not to introduce a contract, and how to test against interfaces). Estimate under a day of onboarding per engineer, plus a short architecture briefing. The larger effort is the first inventory and standards document; without it, adoption is cosmetic.

TPM recommendation. Viable as a low-cost, low-commitment standardization lever for a Laravel 11/12 modular codebase, contingent on: confirming the archive/release contradiction, pinning and mirroring the package, piloting in one internal package, and designating an owner with a fork contingency. Do not frame it as a strategic platform dependency — its value is convention enforcement, and its code is cheap enough to replace.