Product Decisions This Supports
- Build vs. buy, resolved. The v1.0.0 milestone is the decision point where the answer flips from "evaluate" to "adopt." A 1.0 tag is a public commitment to semantic versioning: breaking changes move to a major bump with a documented upgrade path. That converts an open-ended build-vs-buy debate into a bounded one — we can budget an upgrade line item per Laravel major instead of carrying indefinite maintenance risk.
- Roadmap de-risking. Anything we don't build is capacity returned to the roadmap. This package removes a well-bounded concern from our backlog and replaces it with a dependency we can pin (
^1.0) and schedule against.
- Platform lifecycle planning. Laravel majors ship roughly yearly with overlapping support windows. A 1.0 release with a declared version matrix lets us align our Laravel upgrade cadence with our dependency upgrades rather than discovering incompatibility mid-cycle.
- Feature scoping and non-goals. Documenting the package as the sanctioned solution for its concern lets us say no to parallel homegrown implementations — the most common source of long-term maintenance drag in a Laravel codebase.
- Surface-area triage. The same package may be fine for internal tooling and inappropriate for customer-facing paths with SLAs. The 1.0 tag lets us make that call per surface rather than treating adoption as all-or-nothing.
- Vendor and succession risk. A 1.0 release is a natural checkpoint to assess maintainer concentration, release cadence, security disclosure process, and whether the data/interfaces are portable enough that a fork is a weekend rather than a quarter.
- Onboarding and hiring. Laravel-native conventions (service provider, config publishing, facade) mean new engineers read the integration in minutes. That is a real, quantifiable ramp-cost reduction.
When to Consider This Package
Adopt when most of these hold:
- The team is already on Laravel and the package respects framework conventions rather than fighting them — publishable config, container bindings, no monkey-patching of core.
- The concern is well-bounded and non-differentiating. If it isn't part of our competitive advantage, a maintained dependency beats our implementation.
- The 1.0 tag is backed by artifacts, not just a number: a changelog, an upgrade guide, a CI matrix across supported PHP and Laravel versions, and a security policy.
- Our Laravel and PHP versions are inside the declared support matrix, including the LTS we plan to run.
- License is compatible with our distribution model, and the dependency tree is shallow enough that a transitive conflict won't block a future Laravel upgrade.
- There is an escape hatch: data lives in our schema, the public API is narrow enough to wrap behind our own interface, and swapping it out is measured in days.
Look elsewhere when:
- The package reaches into framework internals or requires patching Laravel to work — that is an upgrade tax we will pay every year.
- v1.0.0 arrives with no upgrade guide and no stated deprecation policy. A version number without those is cosmetic.
- One maintainer, no succession plan, and no security contact. Acceptable for a dev-only tool; not for anything on the request path.
- The concern overlaps with a first-party Laravel feature that is likely to absorb it. Building on top of a package the framework is about to subsume is a known dead end.
- It duplicates something we already run. Two solutions to one problem is worse than either alone.
- The integration surface is larger than the problem. If wiring it up costs more than the code it replaces, the buy case fails on its own math.
How to Pitch It (Stakeholders)
To executives: We are standardizing on this package at its first stable release. That timing matters — 1.0 means the maintainers have committed to a stability contract, so we can plan upgrades instead of reacting to them. The business case is capacity: it retires a piece of undifferentiated infrastructure from our roadmap and replaces an open-ended maintenance obligation with a pinned dependency and a predictable annual upgrade. Risk is bounded by a narrow integration surface and a documented exit path. The ask is a time-boxed evaluation, not a permanent commitment.
To engineering: Adopt at ^1.0, wrap it behind our own interface so the dependency never appears in domain code, and add the Laravel upgrade to our existing annual cycle rather than treating it as a separate project. Before merge, we verify the supported version matrix covers our LTS, confirm the upgrade guide exists, and confirm the package's tests run in our CI. If the wrapper is thin, a future swap is an afternoon.
The ask: a two-week spike behind a feature flag, a pinned version in composer.json, and a short ADR recording why we adopted it, what we would replace it with, and the trigger conditions for revisiting.