Laraflow Laravel Package

Product Decisions This Supports

• Modelling lifecycle state on existing entities without a schema rewrite. Orders, invoices, subscriptions, support tickets, KYB/KYC applications, content drafts, and approval requests all have a "status" column today. LaraFlow lets us turn that string column into an explicit, enumerable state machine without a new database or service.
• Build vs. buy for workflow engines. This is the "build" end of the spectrum: ~a few hundred lines in our own repo vs. adopting a heavier orchestrator (Temporal, Camunda/Zeebe, AWS Step Functions). It is a defensible choice when the workflow is per-record lifecycle with human/product gates, not long-running distributed sagas with timeouts, retries, and cross-service compensation.
• Feature roadmap: accelerating "approval-ish" features. Multi-step review, moderation queues, escalation, and publish/archive flows are recurring requests. A shared flow vocabulary (states, transitions, guards) means the second and third such feature cost materially less than the first.
• Instrumentation and analytics decisions. Because every transition is observable via Laravel events, product can get a free state-transition event stream — funnel analysis ("what % of applications reach approved?"), cycle-time measurement, and stuck-record detection (records parked in a state past an SLA).
• Risk decisions: enforcing business rules at the boundary. Guards move "can this user cancel this order?" from scattered controllers/policies into one testable place. That is a reliability decision as much as a code-organization one, and it directly reduces the class of bug where an illegal transition silently corrupts data.
• API/UX decisions. An explicit transition list is a ready-made source for available actions on a detail page (canCancel, canRefund), so the UI stops re-deriving permissions from status strings in JavaScript.

When to Consider This Package

Consider it when:

• The domain is a single Eloquent record moving through a known, finite set of states — and the team already lives in Laravel.
• You want explicit transitions, guards, and events but do not want to hand-roll a status enum plus a pile of if statements and scattered $model->status = ... writes.
• You need auditability and hooks (email on shipped, webhook on approved) and prefer Laravel events over an internal callback registry.
• The team is small and operational simplicity dominates — no new infrastructure, no extra service to page someone about.
• You want generators and conventions so junior engineers can add a state safely rather than inventing a fourth way to update status.

Look elsewhere when:

• Maintenance risk is disqualifying. Last release was April 2023 and the project has ~66 stars. For a package that will sit on the critical path of order or payment state, treat this as vendored source you own, not a dependency you can lean on. Budget for forking it or wrapping it behind an internal interface so it can be swapped.
• The workflow is long-running or distributed: multi-day timers, external service callbacks, retries with backoff, compensation/rollback across services, or human tasks spanning days. That is Temporal/queue-worker territory; LaraFlow is synchronous in-request state math.
• You need versioned flow definitions applied to in-flight records, or runtime-editable workflow config by non-engineers. This package is code-defined, not a visual builder.
• Parallel/compound states, sub-flows, or join/fork semantics are required — a hierarchical state machine it is not.
• Multi-tenant or high-volume concurrency where transition races matter. The package gives you no locking; you must add optimistic concurrency (where status = 'expected' or lockForUpdate) yourself, and you should confirm that before committing.
• The org has standardized on event sourcing or a BPMN engine, in which case a bespoke package fights the platform.

Migration/compliance caveat: for regulated flows (payments, KYC), verify that events alone give you a durable audit log. Events are fire-and-forget unless you persist them; you likely still need a state_transitions history table.

How to Pitch It (Stakeholders)

To executives — one paragraph: LaraFlow is a small, MIT-licensed library that makes "where can this record go next?" an explicit, enforced rule in our Laravel codebase instead of an unwritten convention spread across the app. The business value is fewer status-related production bugs, faster delivery of the approval-style features customers keep asking for, and a built-in event stream that tells us how long records sit in each step. The cost is near zero in licensing and infrastructure; the real cost is that the package is lightly maintained, so we should adopt it behind our own thin interface and treat it as code we own.

To engineering — the honest technical brief:

• It is a convention layer, not a framework: states, transitions, guards, events, generators, and a fluent transitionTo-style API on Eloquent models. Low conceptual overhead, easy code review.
• The win is co-locating authorization with the transition and making illegal transitions throw rather than corrupt data. That is a genuine correctness improvement over ad-hoc status updates.
• The risk is staleness: no release since April 2023. Mitigate with (a) wrapping it behind an internal StateMachine contract, (b) pinning and vendoring if needed, (c) a spike to confirm Laravel 11/12 compatibility and PHP 8.3 support before we depend on it.
• Known gaps to own: no built-in concurrency protection on transitions (we add compare-and-set on the status column), no persisted transition history (we add a table if we need an audit trail), and no versioned flow definitions (in-flight records keep their behavior; changing a flow is a deploy-time concern).
• Recommend a timeboxed pilot on one non-critical model (e.g., content publishing, not payments) with a go/no-go after two sprints. Success criteria: transitions are covered by tests, no direct status writes remain in that model, and the team can add a state in under an hour.

Recommendation: Adopt as a reversible, internally-wrapped dependency for single-record lifecycle flows in Laravel. Do not adopt for payment-critical or distributed workflows until we have the concurrency guard and audit table in place.