Eloquent State Machine Laravel Package

Product Decisions This Supports

• Build vs. buy for lifecycle logic. Any feature with an object that moves through defined stages — order fulfillment, subscription billing, KYC/onboarding, support tickets, content publishing, refunds — is a state machine in disguise. This package lets you evaluate "do we adopt a state machine abstraction?" quickly by reading a small, MIT-licensed reference implementation rather than committing to a heavier framework.
• Feature scoping and edge-case discovery. Writing down states and legal transitions forces the product question early: what are the invalid moves, who is allowed to make each one, and what happens on an illegal request? That artifact is directly reviewable with design, support, and compliance before engineering estimates the work.
• Roadmap sequencing for workflow features. Once transitions are explicit, you can sequence the roadmap by transition rather than by screen: ship "pending → approved" first, defer "approved → refunded" to a later quarter, and communicate scope in terms stakeholders recognize.
• Where to enforce invariants. A decision on whether state rules live in the model, a service layer, or a dedicated workflow engine. This package's approach (state as an Eloquent attribute, transitions as guarded methods) is the lightweight end of that spectrum — useful for calibrating how much ceremony your domain actually warrants.
• Instrumentation and reporting design. Explicit states give you the dimensions for funnel and SLA analytics ("time in awaiting_review"), which is a product decision about what to measure, not just an engineering one.

When to Consider This Package

• Simple, linear or lightly branching lifecycles. A handful of states with single-owner transitions. If you need parallel regions, hierarchical states, or long-running sagas with compensation, this is the wrong altitude.
• You intend to vendor or fork, not depend. With 1 star and 0 dependents, treat it as a readable pattern source: copy the ~few hundred lines into your app, adapt to your conventions, and own the maintenance. That converts the abandonment risk into an acceptable one-time cost.
• You want to avoid a larger dependency for a small need. If spatie/laravel-model-states or a full workflow engine is more surface area than the feature justifies, a small in-house state machine is the better trade — this repo shows roughly what that costs.
• Compatibility must be verified first. Check the Laravel and PHP version constraints in composer.json against your stack before anything else; a package this small and this inactive is unlikely to have kept pace with recent Laravel majors. Budget a spike to confirm it installs and the tests pass on your versions.
• Look elsewhere when you need an auditable transition history out of the box, role/permission-aware guards, queued side effects on transition, admin UI for manual overrides, or any form of vendor support or security responsiveness. In those cases prefer a maintained package (Spatie's model-states, or a BPM/workflow engine) or build the thin layer yourself with tests.

How to Pitch It (Stakeholders)

To executives: This is a low-cost evaluation, not a platform commitment. It gives us a concrete, MIT-licensed example of how to encode business rules like "an order can only be refunded after it ships" directly in the codebase, so those rules are enforced in one place instead of scattered across screens. The package itself is small and unmaintained — one star, no downstream users — so the recommendation is to use it as a design reference and internalize the pattern, not to take on a long-term dependency. Expected cost is a short engineering spike; the payoff is fewer order/onboarding inconsistency bugs and clearer, earlier conversations about what our workflows actually are.

To engineering: Read it as a pattern, not a library. It models state as an Eloquent attribute with guarded transition methods — the minimum viable state machine. Confirm PHP/Laravel compatibility, then fork the approach into our own app/ namespace with tests and an explicit transition table rather than adding it to composer.json. If the domain turns out to need transition auditing, role-aware guards, or side effects on transition, we should stop and adopt a maintained package instead of growing this code ourselves. Decision requested: approve a one-to-two day spike to prototype our primary lifecycle (e.g., orders) against this pattern and report back on whether it holds.