States Bundle Laravel Package

Product Decisions This Supports

• Build vs. buy on lifecycle modeling. Informs whether to keep encoding status logic as match($order->status)/if ladders scattered across controllers, jobs, and observers, or to formalize state transitions so behavior lives next to the state it applies to. This is the recurring decision behind any entity that "does different things depending on where it is in its life."
• Roadmap scoping for lifecycle-heavy epics. Directly relevant to order fulfillment, subscription/dunning states, invoice and payout lifecycles, KYC/onboarding, document approvals, and ticket triage on Laravel services — each is a bounded state graph with per-state behavior, and each benefits from the same modeling discipline.
• Prioritizing maintainability work. Gives a concrete, low-risk refactor target: extract sprawling conditional business logic into discrete state classes or enum-backed transitions. The tradeoff is explicit — more small classes/enums up front, far cheaper change and per-state testing later.
• Package/architecture selection — the honest verdict. The artifact under review (teknoo/states-bundle) is a deprecated, archived Symfony bundle (2 stars, 0 dependents). The real product decision is not "adopt this bundle" on a Laravel stack, but "do we want formal state handling at all, and if so with which Laravel-native implementation?" The intended successor is teknoo/states 3.1+, and even that must be validated as maintained.
• Tech-debt triage. If this bundle (or its generated classes) already exists in any legacy service, this justifies a scheduled migration item off an archived dependency — especially because the Symfony-bundle half provides nothing reusable in Laravel.

When to Consider This Package

• Do not adopt teknoo/states-bundle for new work, and not on Laravel. It is archived and explicitly deprecated in its own description, it is a Symfony bundle (no service provider, publishable config, or facade maps to Laravel), and a modern Laravel composer.json will likely fail resolution against its Symfony-pinned constraints. Two stars and zero dependents mean no community safety net, no security patching, and no upstream fixes.
• Consider only the successor (teknoo/states 3.1+) — and only if: you specifically want the State pattern expressed as generated PHP classes, you are comfortable with a codegen-first workflow, your state graph is static and known at design time, and you have confirmed an active release cadence and PHP/Laravel version support. Treat the bundle purely as design documentation.
• Look elsewhere if:
  • You want transitions persisted, audited, and queryable — prefer Laravel-native options: PHP 8.1 backed enums with transition methods, a small StateHydrator + Eloquent cast, or a mature package such as Spatie's model-states.
  • You need admin-configurable or visually edited state graphs, or non-developer ownership of transitions.
  • You require vendor support, SLAs, or a maintained dependency in the critical path of core domain logic.
  • The state graph is small (three or four branches) — a formal state machine there is over-engineering; an enum is enough.
• If evaluating the successor anyway, gate on: active maintenance status, transitive dependency footprint stripped of the bundle, whether codegen runs at build time (committed output) vs. runtime, and whether the emitted code passes our PHPStan/Psalm and coding-standard baseline.

How to Pitch It (Stakeholders)

Executive summary. This specific package is a dead end — it is deprecated by its author, archived, has effectively no users, and is a Symfony bundle that does not fit our Laravel stack. We should not build on it. But the problem it addresses is real and recurring: our lifecycle logic (order status, subscription states, approvals, onboarding) tends to accrete into large conditional blocks that are expensive to change and risky to test, and that logic sits directly in the path of core business behavior.

Recommendation. Treat this as a signal to standardize on a maintained, Laravel-idiomatic workflow approach — backed enums with explicit transition methods or an actively maintained package (e.g., Spatie model-states) as the default. Consider teknoo/states 3.1+ only if the team specifically wants generated state classes and the library proves alive. Do not greenlight the deprecated bundle under any circumstance; at most, harvest it as a design reference.

For engineering. Low effort to evaluate, near-zero migration cost today if we have no internal dependents, and the decision costs a design conversation rather than a build. Run a short timeboxed spike on a throwaway branch — generate or hand-write one real state machine (e.g., the order lifecycle), diff it against a hand-written enum-based equivalent, then choose. Prefer build-time codegen with committed output so the runtime dependency disappears and only the build step is at risk. If emitted classes are committed, document the regeneration command or the next engineer will edit generated code in place. If the bundle already exists in any legacy service, flag it as archived-dependency debt and scope a move to native enums or a maintained package.

Risk framing. Adopting an archived, single-maintainer dependency with 2 stars concentrates risk on a component sitting in the critical path of core business logic — the worst place for an unmaintained library, and one that cannot ship a security fix. The high "opportunity" signal reflects an unoccupied niche, not a healthy dependency; the low overall score correctly identifies why it is unoccupied. The pattern is sound; this artifact is not.