Weave Code
Laravel State Machine Laravel Package
jobmetric/laravel-state-machine
jobmetric/laravel-state-machine adds finite state machines to Laravel applications. Define states and transitions for Eloquent models, enforce guards, trigger events and callbacks, and manage safe state changes with a clean, configurable API.
At a glance
Frequently asked questions about Laravel State Machine
- What is jobmetric/laravel-state-machine used for in Laravel?
- It adds finite state machines to Laravel applications, letting you define states and transitions for Eloquent models. It supports guards, events, callbacks, and safe state changes through a configurable API. It fits service-layer or domain-model patterns and can also expose transition data for UI rendering and workflow orchestration.
- How do I install jobmetric/laravel-state-machine with Composer?
- Install it with composer require jobmetric/laravel-state-machine. The package is Laravel service-provider driven, so package discovery should register it in a standard Laravel app. Then follow the README to publish or generate the state machine stub for your domain, and verify the package constraints against your Laravel and PHP versions before committing.
- How do I define states and transitions for an Eloquent model?
- The package is built around a generated state-machine.php.stub, so you define a state machine per domain and map its states and transitions for the model. Keep the generated class in your domain or service layer and route status changes through transition calls instead of writing status columns directly. Review the generated output against your team conventions before rolling it out broadly.
- Can I enforce guards before a state transition?
- Yes. The package supports guards that must pass before a transition is allowed, which helps keep authorization and business preconditions out of controllers. Put guard logic in the generated state machine or supporting domain services, and test both allowed and rejected transition paths. Because guards encode business rules, review them like any other domain code.
- Does it trigger events and callbacks on state changes?
- Yes. The package can trigger events and callbacks when transitions occur, so you can integrate with observers, jobs, and broadcasting. Treat those hooks as part of your workflow contract and test their side effects. If you already have model observers, avoid duplicating the same side effect in both layers.
- What do getCurrentState and getAllTransitions return?
- The provided release context does not specify whether getCurrentState returns a raw string, an enum, or a state object, while getAllTransitions exposes transition data for fields. That return type matters for API serialization and admin UI rendering, so verify it in the source or with a quick test before relying on it. Programmatic introspection is useful for audit tooling, but consider wrapping it in your own adapter to lock the contract.
- Which Laravel and PHP versions does version 2.4.0 support?
- The 2.4.0 release bumps orchestra/testbench, which is a positive sign for current Laravel test harness alignment, but the provided notes do not list exact Laravel and PHP constraints. Check composer.json and run your CI matrix in a scratch branch before pinning 2.4.0. If you are on older Laravel or PHPUnit versions, treat the testbench change as a compatibility gate.
- Is it safe to run state-machine:debug in production?
- state-machine:debug is an Artisan command for inspecting transition graphs without writing code, which is useful for ops and QA. The provided context does not confirm whether it has a production environment guard, so do not assume it is safe to expose in production. Run it in staging or behind an environment or authorization guard, and consider wiring it into a staging-only CI job for graph validation.
- How does it compare with spatie/laravel-model-states?
- This package is a competing state machine primitive to spatie/laravel-model-states rather than a complementary one. Pick one state machine approach per domain to avoid dual state models and conflicting transition rules. If you already use Spatie's package, evaluate migration cost and generated-code ownership before adding this one.
- What happens to generated state classes when the package stub changes?
- Because the state machine is generated from a stub, your team owns the generated state classes after generation. Upgrading the package does not automatically rewrite existing generated code, and a future 3.x stub change may require manual regeneration or a diff review. Keep generated classes under version control and budget recurring review time when the package bumps minor versions.
Weaver
How can I help you explore Laravel packages today?