States Laravel Package

Product Decisions This Supports

• Roadmap scoping for stateful features. Any roadmap item involving multi-step workflows — order fulfillment, payment/refund lifecycles, subscription states, approval chains, ticket status, onboarding/account states — is a candidate. This package supplies the mechanism for modeling states and transitions explicitly rather than as a growing switch/if ladder.
• Build vs. buy. The decision is "buy the plumbing, own the states": the library supplies dispatch, visibility rules, Doctrine hooks, and a PHPStan extension, while your state definitions and business rules stay in your code. It is not a workflow engine, event bus, or orchestrator — it solves exactly one problem, replacing conditional sprawl in rich domain objects.
• Tech-debt prioritization. A credible justification for a "reduce conditional complexity" backlog item where an existing domain object is a defect hotspot. Adoption is a deliberate migration, not a drop-in — budget it as such.
• Use cases where persistence and static analysis matter. Doctrine ORM/ODM entity state and CI-checked state-aware method resolution are the sharpest differentiators: state handling becomes reviewable in code, not just at runtime.
• Not a fit for greenfield Laravel work where Enum + match or a Laravel workflow package covers the need at zero added dependency risk, or where the domain is Eloquent-anemic and the conditional logic lives in service classes — this library does not address that.

When to Consider This Package

Adopt when:

• You have genuinely stateful domain objects with many states and transition-heavy behavior, and current conditionals are a measurable maintenance/defect hotspot.
• Your platform baseline is already PHP 8.4+ (a hard gate — treat it as a filter, not a forcing function).
• You already use Doctrine ORM/ODM, or can adopt AbstractStandardObject, so the persistence integration earns its keep.
• Your team enforces strict typing and PHPStan max-level analysis, and is willing to absorb the builder/closure idiom (state methods return closures bound to the proxy — powerful, but it defeats IDE go-to-definition and is not guessable).
• You accept BSD-3-Clause and a single-runtime-dependency surface, and you are prepared to vendor-and-freeze (pin exact versions, keep a forkable internal branch).
• You can place the library behind an internal StateMachine/HasStates seam so domain classes never import it directly.

Look elsewhere when:

• The model has 2–4 states — enums and match are clearer and dependency-free.
• Community support or hiring matters: 10 stars, 0 dependents, bus factor 1, no commercial maintainer.
• You are on PHP < 8.4 or your CI cannot tolerate a PHPStan extension that tracks PHPStan internals outside its BC promise.
• You need documented SLAs, security processes, or vendor accountability.
• The domain is Eloquent-centric with anemic models and service-layer logic.
• Candidate objects are serialized (sessions, queues, caches) — the serialization semantics need a spike first.
• Hot request paths where per-call debug_backtrace() visibility resolution is measurable.

How to Pitch It (Stakeholders)

For executives: This is a small, focused library that implements the standard State pattern for objects whose behavior changes with their state — the kind of logic that otherwise accumulates in large, error-prone conditionals. It has one runtime dependency, a permissive BSD-3-Clause license, and pairs with our static-analysis standards, so it reduces the bug surface in complex workflows. The trade-offs are real: low community adoption (a few stars, no known dependents, effectively a single maintainer) and a hard PHP 8.4+ requirement. We should treat adoption as a narrow, deliberate bet on one or two complex domain workflows — not a platform-wide standard — and validate maintenance risk before committing further.

For engineering: You get the State pattern handled: state classes with inheritance and real method visibility, automated state switching driven by property assertions and constraints, Doctrine integration for entities/documents, and a PHPStan extension so CI understands state-dispatched calls. Quality signals are strong — strict typing, PSR-12, PHPStan at max, PHPUnit 13, and a CI that fails on any deprecation or notice. Cost of entry: the builder/closure model must be learned and documented internally, and the PHPStan extension follows PHPStan internals, so expect 2–4 bump-and-fix cycles per year and a decision on whether to run the extension unloaded by default.

Recommended next step: a time-boxed spike (two sprints) against one real roadmap workflow, behind an internal seam and with parity tests against the existing conditional path. Measure (a) whether conditional sprawl is measurably removed, (b) onboarding cost for two engineers, and (c) actual upgrade/maintenance burden. Pin versions, document the idiom locally, and decide on wider rollout only at the quarter boundary.