Weave Code
State Workflow Laravel Package
ringierimu/state-workflow
State workflow for Laravel Eloquent models: define states and allowed transitions, guard changes with custom rules, and react to transitions via events. Centralizes business status logic so it stays clean, testable, and consistent across your app instead of scattered controllers.
Laravel State Workflow provide tools for defining and managing workflows and activities with ease.
Frequently asked questions about State Workflow
- How do I install ringierimu/state-workflow in a Laravel app?
- Install it with Composer using composer require ringierimu/state-workflow, then publish the package config. You then add the package trait to each Eloquent model that needs lifecycle behaviour. No service provider wiring beyond the standard Laravel package auto-discovery is required. The mechanical setup is quick, so budget your real effort for retrofitting existing status logic onto the declared graph.
- Which Laravel and PHP versions does state-workflow 5.0 support?
- Version 5.0.0 requires PHP 8.3 or 8.4 and Laravel 11 or 12. If a service is still on Laravel 10 or PHP 8.1/8.2, the framework upgrade has to land first, because the package adoption is a follow-on rather than a driver. The 4.x to 5.0.0 changelog advertises only requirement bumps and no API changes, but treat that as unverified: read the diff between 4.0.0 and 5.0.0 and run your own transition tests before upgrading.
- How do I define states and allowed transitions for an Eloquent model?
- You declare states and the transitions allowed between them directly on the model, and the package mediates which transitions are legal from the current state. State is typically backed by a persisted column on the table, so the declared graph effectively becomes part of your schema. Because of that, treat graph changes as data changes: removing a state means migrating any records still sitting in it.
- Can I allow a transition for one user and deny it for another?
- The package is built around guarding state changes with custom rules, which is where per-actor authorisation belongs. Implement the rule against your policy or gate so the same transition can be permitted for one role and rejected for another. Check the package docs for the exact guard hook signature before you build your authorisation layer on top of it, and cover the deny path in tests.
- Does the package emit events so I can run payments, notifications, or API calls on transition?
- Yes, reacting to transitions via events is part of the package's core design, so side effects can be attached as listeners rather than written inline in controllers. Orchestration of those side effects is still your responsibility, so keep external calls idempotent and consider queuing anything slow or failure-prone. Decide deliberately whether a failed listener should roll back the state change or be retried separately.
- Does state-workflow store a history or audit log of state changes?
- The package centralises transitions and gives you a consistent event surface, which makes an audit trail far easier to build, but do not assume it persists a full history of who changed what and when. Confirm in the docs whether any history is stored, and if not, record transitions in a listener into your own audit table. Capture the actor, timestamp, previous state, and new state at minimum.
- How do I handle two requests attempting a transition on the same record at once?
- Concurrency is handled at the application layer, not assumed by the package. Wrap the transition in a database transaction and take a row lock with lockForUpdate, or use an optimistic version check, so the second request sees the updated state and is rejected as an illegal transition. Add a test that simulates the race, since this is exactly the kind of bug that only shows up in production volume.
- Is there a way for admins to force or bulk-correct a state, bypassing the transition graph?
- You need an escape hatch for administrative corrections, because a strictly guarded graph will block legitimate fixes such as data repairs or support escalations. Check whether the package exposes a bypass, and if not, build a dedicated service or Artisan command that writes the state field directly and always records an audit entry. Keep that path out of normal request handlers so it stays a deliberate, logged exception.
- How should I test state workflows in my Laravel app?
- Because the graph is declared on the model, you can assert legal and illegal transitions in ordinary unit or feature tests without touching HTTP. Prove the pattern end to end on one bounded, well-understood lifecycle, such as an onboarding funnel, before rolling it onto your most business-critical flow. When evaluating 5.0.0, run your own transition tests against it rather than trusting a one-line changelog.
- Is ringierimu/state-workflow a good choice versus hand-rolled status checks or other state machine packages?
- The main argument for it over scattered if checks is that the legal-transition graph lives in one declarative place, so status logic stays testable and consistent across controllers, jobs, and observers. Alternatives are hand-rolled guards or another Laravel state machine package, and the trade-off is adding a dependency on the critical path of core domain writes. Check the maintainer's release cadence, issue-response record, and bus factor over the last twelve months, and know your rollback story before you commit.
Weaver
How can I help you explore Laravel packages today?