Eloquent State Machine Laravel Package

Product Decisions This Supports

• State machine modeling for Eloquent models: This package lets you formalize status/state transitions (e.g., draft → review → published) directly on Eloquent models, so product decisions about workflow rules (who can move what, when, with what side effects) become explicit code rather than scattered if ($status === ...) checks.
• Workflow and lifecycle features: Relevant for roadmap items involving approvals, order fulfillment, subscription lifecycle, onboarding progress, or any domain object with a governed status field. It supports decisions about how strict or permissive transitions should be, and what happens on each transition (events, guards, side effects).
• Build vs. buy: The core concept is small enough to hand-roll, but standardizing on a package reduces bespoke edge cases (invalid transitions, guard logic, transition hooks). At v0.1.0 the build-vs-buy calculus is tilted by maturity risk — see the next section.
• Use cases: single-model or multi-model state flows where transitions need auditing, guard conditions, or event hooks; useful as a reference implementation when evaluating whether to adopt a package versus build an internal abstraction.

When to Consider This Package

Consider it when:

• You have Eloquent models with a real state lifecycle and non-trivial transition rules (guards, allowed transitions per role, side effects on transition).
• You want transitions to be first-class, testable, and discoverable rather than implicit in controllers.
• You're evaluating packages in a non-production spike or internal prototype where API stability matters more than test coverage and docs.

Look elsewhere or defer adoption when:

• You need production-grade guarantees now. v0.1.0 explicitly lacks proper tests and documentation; the API is described as stable-for-1.0, but "stable" without a test suite is a claim, not a guarantee.
• Your team requires documented upgrade paths, security review, or vendor/maintainer support commitments.
• Your workflow needs are simple (two or three statuses, linear flow) — a small internal enum + guard methods may be cheaper than adding a dependency.
• You need community momentum signals (downloads, contributor base, issue responsiveness) before committing to a dependency.

How to Pitch It (Stakeholders)

For executives (one-liner): A small Laravel package that makes application workflows (approvals, order status, publishing) explicit and auditable in code — promising for standardizing workflow logic, but currently pre-1.0 and not yet hardened with tests or docs, so we recommend a time-boxed evaluation rather than production commitment.

For engineering: bjuppa/eloquent-state-machine v0.1.0 ships what the maintainer intends as the 1.0 API, but with no meaningful test suite or documentation. Treat it as an evaluation candidate: spike it against one real workflow, assess the API for fit, and track the maintainer's documented follow-up work (tests + docs) before we depend on it in production. Decision needed: do we invest in a spike now, or wait for 1.0 with tests and docs?