State Workflow Laravel Package

Product Decisions This Supports

• Build vs. buy for workflow/state management: If your product has entities with lifecycle states (orders, subscriptions, invoices, onboarding, approvals, content moderation), this package is the "buy/borrow" option — it replaces hand-rolled status enum columns and ad-hoc if ($model->status === ...) guards with an explicit, testable state machine definition.
• Feature: auditable state transitions. Supports product requirements around "who changed what, when, and why" (approval trails, compliance, customer-facing status history) without bespoke code per entity.
• Feature: gated transitions. Business rules (only finance can approve refunds, only after payment settles) can be expressed declaratively rather than scattered across controllers — useful for roadmap items involving approvals, escalation, or multi-step onboarding.
• Roadmap sequencing: A breaking major (5.0) means adopting now locks you to Laravel 11/12 and PHP 8.3/8.4. If you're mid-upgrade on the framework, this becomes an upgrade-order decision: framework first, then workflow package.
• Scope control: Standardizes state handling across teams/products so multiple squads don't each invent a slightly different transition mechanism — reduces long-term maintenance and onboarding cost.

When to Consider This Package

Consider it when:

• Your domain has genuinely stateful entities with more than a trivial number of states/transitions, and the transition rules are business-meaningful (approvals, eligibility, retries).
• You need consistent enforcement: transitions validated in one place, not in controllers, jobs, and observers independently.
• You want transition side effects (events, notifications, audit records) wired to state changes rather than sprinkled around.
• Your stack is already on, or committed to, Laravel 11/12 and PHP 8.3/8.4 — the 5.0.0 baseline.
• You value a small, focused dependency over a full BPM/no-code workflow engine.

Look elsewhere when:

• Your "workflow" is really just 2–3 statuses on one model — native enums plus a policy or two are cheaper and clearer.
• You need visual workflow design, human task queues, SLA timers, or long-running orchestration — that's a workflow/BPM platform or queue-based saga, not a model-level state machine.
• You are pinned to Laravel 10 or PHP 8.1/8.2; 5.0.0 will not install, and 4.x is now the legacy branch. Confirm the maintainer's backport/security posture before relying on 4.x.
• You need a large third-party integration ecosystem, vendor SLA, or commercial support — this is a community package; assess maintainer responsiveness and release cadence as part of the buy decision.

How to Pitch It (Stakeholders)

For executives (30 seconds): We're evaluating a small open-source Laravel component that makes business rules around status changes — order lifecycle, approvals, onboarding — explicit and auditable instead of buried in code. It's low-cost, low-lock-in, and reduces a class of bugs where records end up in states they shouldn't. The new 5.0.0 release is a compatibility update: it now requires Laravel 11/12 and PHP 8.3/8.4, which aligns with our platform upgrade path. No decision needed today beyond confirming our framework timeline.

For engineering leads: Version 5.0.0 is a breaking, requirements-only release — it raises the floor to Laravel 11/12 and PHP 8.3/8.4 and drops older framework/runtime support. There are no new features or deprecations to design around, but it does mean: (1) adoption is gated on our framework upgrade, (2) any existing 4.x usage needs a planned major-version bump, not a patch drop-in, and (3) we should confirm the 4.x branch still receives fixes if we can't move immediately. Recommendation: treat this as the version we target for new work, with adoption timed to the Laravel/PHP upgrade rather than before it.

Risk note to flag: a requirements-only major signals maintenance activity but also that the package rides the framework's support window. Before committing, check recent commit activity, issue responsiveness, and test coverage on the 5.x line — that's the real build-vs-buy signal for a single-maintainer dependency.