Laravel State Machine Laravel Package

Product Decisions This Supports

• Build vs. buy for workflow/state logic: A drop-in replacement for asantibanez/laravel-eloquent-state-machines means adopting this is a low-switching-cost decision — teams already on the original package can migrate without rewriting transition definitions, guarding that roadmap decision behind a Composer swap rather than an engineering project.
• Feature scoping for auditable workflows: State machines with history tracking and enum support map directly to compliance-sensitive flows (order lifecycles, subscription billing, approvals, onboarding). This supports committing to "state transitions are logged and typed" as a product requirement rather than a bolt-on later.
• Roadmap timing on framework upgrades: The v1.0.1 Laravel 13 compatibility (with PHP 8.2 correctly excluded per framework requirements) removes this package as a blocker on the platform-upgrade roadmap. PMs can sequence Laravel 13 migration without carving out a package-replacement workstream.
• Risk reduction on transaction-sensitive features: The transaction-boundary fix means transitions wrapped in an existing DB::transaction() no longer create nested savepoints. This de-risks features where a transition and surrounding writes must commit or roll back atomically (e.g., "place order" = decrement inventory + transition state), and it directly reduces a class of production incidents that are painful to reproduce.
• Use cases to prioritize: order/fulfillment lifecycles, subscription dunning and cancellation flows, KYC and approval pipelines, ticket/triage workflows, and any funnel where PMs need per-transition funnel analytics from persisted history.

When to Consider This Package

Consider adopting when:

• Your domain has an explicit, finite set of states with defined allowed transitions — and you want those rules enforced in one place instead of scattered across controllers, observers, and jobs.
• You already use (or are evaluating) asantibanez/laravel-eloquent-state-machines; the drop-in compatibility makes this a low-risk trial.
• You need transition history/audit trails as a product or compliance requirement, not an afterthought.
• You're on Laravel 11/12/13 with PHP 8.2–8.4 on MySQL, PostgreSQL, or SQLite — the supported matrix is current and broad.
• You run transitions inside larger database transactions and need predictable commit/rollback semantics.

Look elsewhere when:

• Your workflow is genuinely open-ended (human-driven BPMN, long-running multi-service sagas) — a single-model Eloquent state machine won't model cross-service orchestration or compensation logic.
• You need a visual workflow designer, SLA timers, or non-engineer-editable process definitions; those are a different product category.
• Your team is not on a supported Laravel/PHP combination, or you depend on databases outside MySQL/PostgreSQL/SQLite.
• The workflow is trivial (two states, one transition) — a boolean column with guard clauses is cheaper to own than a new dependency.
• You require vendor-backed SLAs; this is community-maintained and explicitly positioned as a fork/replacement, so continuity risk should be acknowledged.

Caveats worth stating plainly: the version number (v1.0.1) signals an early-stage project despite a mature feature set inherited from the original. The package is a fork, which raises the question of long-term divergence from upstream and who absorbs maintenance if upstream stalls.

How to Pitch It (Stakeholders)

To executives: This is a small, low-cost library that makes our workflow logic explicit, auditable, and consistent — which shortens delivery on any feature involving approvals, order lifecycles, or subscription changes, and reduces the "states got out of sync" class of production bugs. The latest release adds Laravel 13 support (keeping our platform upgrade unblocked) and fixes a transaction-handling issue that could otherwise cause silent data inconsistencies in our highest-risk flows. It's a drop-in replacement for a package already common in the Laravel ecosystem, so the switching cost and lock-in are both low.

To engineering: v1.0.1 adds Laravel 13 to Composer requirements and CI (PHP 8.2 skipped on 13 per framework constraints), and changes StateMachine to check DB::transactionLevel() before opening a transaction — so transitions reuse an ambient transaction instead of nesting savepoints, which matters on stricter database configurations. Typing on State was tightened with proper Collection imports, and a new TransactionBoundaryTest plus expanded enum/history coverage backs the behavior. Supported: Laravel 11/12/13, PHP 8.2–8.4, MySQL/PostgreSQL/SQLite.

Recommended PM action: run a one-sprint spike on a single high-value workflow to validate the transition-history and transaction-boundary behavior against our actual database configuration before standardizing on it across domains. Track upstream activity and our fork-pin policy as an ongoing maintenance line item.