Laravel State Machine Laravel Package

Getting Started

1. Install/update the package with Composer and run the package’s publish/migration steps if your app has not already done so.
2. Publish or inspect the package’s state-machine.php.stub first; in 2.4.0 this stub carries improved PHPDoc and is the best reference for expected state/transition shapes and generated class structure.
3. Generate or open a state machine definition for a model field, define the allowed states and transitions, and attach the package’s trait/interface to the Eloquent model.
4. Add the state column/cast to the model and seed/set an initial state.
5. Run php artisan state-machine:debug to inspect registered transitions and current state information before wiring UI or API endpoints.

First practical use case: a model with a status field, such as Order or Invoice, where transitions like pending -> paid -> shipped need centralized guards, actions, and inspection for admin UI buttons.

Implementation Patterns

• Keep transition rules in the generated/state-machine class rather than controllers or form requests; use model methods only as thin entry points.
• Use the new “current state for field” and “all transitions” accessors to build UI: show the current badge, list allowed next transitions, and hide invalid actions per field.
• For models with multiple state fields, always resolve state and transitions by field name rather than assuming a single global state.
• Use guards for authorization/business rules and transition actions for side effects such as sending mail, writing audit rows, or dispatching events.
• After upgrading to 2.4.0, regenerate state machine classes so the improved stub PHPDoc is reflected in your IDE/static analysis. Commit generated code if that is your team’s convention.
• Use state-machine:debug as a local/staging troubleshooting tool when a transition is unexpectedly unavailable; compare registered transitions with the model’s current field state.
• In tests, assert both the current state for the field and the available/all transitions. The 2.4.0 debug-command test coverage is a good signal that command output is intended to be stable enough for diagnostics.
• The orchestra/testbench version change is development/test infrastructure only; it should not affect production runtime behavior.

Gotchas and Tips

• Existing generated state machines will not automatically receive the new stub PHPDoc; regenerate or manually update them after upgrading.
• The debug command is diagnostic, not a migration tool. Use it to inspect configuration/registration, then fix the state machine definition or model state.
• Clear cached config after changing state machine configuration or publishing updated package files.
• Be explicit about field names when using the new current-state/transitions methods, especially on models with more than one state field.
• State transitions are not automatically concurrency-safe. Wrap critical transitions in transactions and consider row locks where two requests could transition the same model.
• Validate transition availability before calling a transition method; do not rely on the UI alone to prevent invalid transitions.
• Watch for stale Eloquent models: refresh the model or re-query before checking current state in long-running requests/jobs.
• Keep transition side effects idempotent or dispatch them after the state change commits; avoid sending notifications before the database transaction succeeds.
• No breaking changes are called out in 2.4.0, but confirm method signatures for the new field-specific accessors in the updated stub before adopting them broadly.
• The Testbench bump can surface test-suite dependency conflicts in package development; treat it as a dev dependency issue, not a production runtime concern.