Version Bundle Laravel Package

Product Decisions This Supports

• Platform upgrade sequencing (PHP 8.4 / Symfony 7.4–8): v4.0.0 explicitly targets Symfony 7.4 and 8 with a PHP >=8.4 floor. Adopting it is a forcing function that pulls the whole application onto PHP 8.4 — treat this as an infrastructure roadmap decision owned jointly with platform/DevOps, not a routine composer update.
• Build vs. buy for extension points: marking all service and command classes final is a deliberate signal that the package is closing its inheritance surface. If your product relies on subclassing its commands/services to add behaviour, the buy-vs-build calculus changes: you now either upstream contributions, wrap via composition/decoration, or replace the package with an in-house implementation.
• Feature roadmap gating: any roadmap item that depends on this package cannot ship until the PHP 8.4 runtime upgrade lands. Use this release to size and schedule that workstream rather than discovering it mid-sprint.
• Ecosystem-alignment risk scoring: a major version bump with a BC break plus a hard runtime floor indicates an actively maintained dependency that is willing to break consumers to stay current. Good for long-term viability, bad for teams that need low-churn dependencies — factor into vendor/dependency risk reviews.
• Support matrix and SLAs: the previous major line (pre-4.0) is now the "legacy" line. Decide explicitly how long you will keep production on it, since it will stop receiving Symfony 8 compatibility fixes.

When to Consider This Package

Adopt when:

• Your application is already on, or is scheduled onto, PHP 8.4+ and a Laravel version that resolves Symfony 7.4/8 components.
• You consume the package as-is — configuration and public API only — and do not subclass its service or command classes.
• You value a maintainer who tracks upstream Symfony releases promptly; the Symfony 8 target implies the package will remain compatible with the next Laravel LTS cycle.
• You need the documented behaviour more than you need to customise internals; the documentation refresh in this release is the intended integration path.

Look elsewhere or defer when:

• You are pinned to PHP 8.2/8.3 (e.g. shared hosting, an inherited Laravel LTS, or an internal platform standard). v4 is not installable for you; stay on the 3.x line and plan the runtime upgrade first.
• Any part of your codebase extends its service or command classes, or type-hints against them in ways that assume extensibility. The final BC break will surface as fatal errors at class-load time, not as a deprecation notice — audit before upgrading.
• Your team decorates or monkey-patches package internals as a routine customisation pattern. That pattern is now explicitly unsupported.
• You require a dependency with a stable public extension contract across majors; the 3.x → 4.x jump shows extension points can be withdrawn at a major boundary.

Migration guidance to carry into the ticket: the upgrade is small but non-optional in scope — bump PHP to 8.4, resolve Symfony 7.4/8, then grep the codebase for extends against the package namespace and convert each hit to composition, a decorator, or a container binding before merging.

How to Pitch It (Stakeholders)

To executives: This is a maintenance major-version release of an actively maintained dependency. It keeps us aligned with the current Symfony and PHP ecosystem, which is the main long-term support risk for a Laravel codebase. There is no new product capability here — the cost is an infrastructure upgrade (PHP 8.4 across our environments) and a bounded audit of our own code. The upside is that we stay on a supported line instead of accumulating an unpatched dependency. The decision required is scheduling, not budget.

To engineering: v4.0.0 modernises for Symfony 7.4/8, raises the floor to PHP 8.4, and refreshes the docs. The one breaking change is that all service and command classes are now final. Practically, that means: no more subclassing the package's commands or services, and no more overriding its internals — use decoration, container bindings, or upstream PRs instead. Before upgrading, grep for extends against the package namespace; those sites fail hard, not softly. Treat the PHP 8.4 requirement as the real work item and the final change as a small, mechanical refactor. Once both are done, the upgrade itself should be uneventful, and we gain a package that will track the next Laravel LTS cycle without another forced migration.