- How do I install ilvalerione/state-machine in a Laravel application?
- Install it with Composer using composer require ilvalerione/state-machine. The package provides Laravel integration, so any service provider it ships with is typically discovered automatically by Laravel. After installation, follow the package README for any optional configuration or publishing steps.
- How do I define states and transitions with this state machine?
- The package uses a fluent definition style, so you declare the states an object can occupy and the transitions allowed between them in one place. This keeps lifecycle rules out of your Eloquent models and controllers. Refer to the README for the exact fluent API method names used in your installed version.
- How do guards work in ilvalerione/state-machine?
- Guards are callbacks attached to transitions that decide whether the transition may proceed. If a guard rejects the change, the package prevents the transition instead of silently updating the state. This lets you encode business conditions such as order payment status or subscription eligibility directly in the transition definition.
- Does the package fire events when an object changes state?
- Yes, events are fired on successful state changes, which lets you hook listeners for side effects such as sending notifications, writing audit logs, or triggering downstream jobs. Because events only fire after a transition succeeds, you can rely on them as a clean signal that the new state is active. Invalid transitions raise an exception instead of firing the event.
- Which Laravel and PHP versions are supported?
- The package is built as a framework-agnostic core with Laravel integration, but the exact supported Laravel and PHP version constraints are defined in its composer.json. Check that file or the README before adding it to an existing project. If you are on an older Laravel release, verify compatibility in the package requirements first.
- Can I use ilvalerione/state-machine outside of Laravel?
- Yes. The core state machine is framework-agnostic, so the state and transition logic can be used in plain PHP projects. The Laravel layer adds convenient integration such as service provider registration and framework events. This makes it possible to share the same lifecycle rules across Laravel and non-Laravel code.
- What happens when an invalid transition is attempted?
- The package throws a clear exception when a transition is not allowed from the current state. This makes invalid lifecycle changes explicit rather than silently corrupting your domain data. You can catch that exception in your application and return a validation error or log the attempt, depending on your needs.
- How should I test a state machine defined with this package?
- Unit test your transitions by asserting that allowed transitions change the state and that disallowed ones throw the expected exception. Also test guard behavior by exercising the conditions that should approve or reject a change. If you rely on events, use Laravel's event faking in feature tests to confirm listeners are dispatched only after successful transitions.
- Is ilvalerione/state-machine suitable for production workflows like order processing?
- It is designed for exactly that kind of domain, including workflows, order processing, and subscription lifecycles. Its value in production comes from making allowed transitions explicit and rejecting invalid ones with exceptions. As with any package, review its test coverage, maintenance activity, and version constraints before relying on it in a critical system.
- How does ilvalerione/state-machine compare with other Laravel state machine packages?
- This package focuses on a lightweight, framework-agnostic core with fluent state and transition definitions, guard callbacks, and events on successful changes. That makes it a good fit when you want explicit lifecycle rules without a large dependency. If you need database-backed transition history, visualization, or a larger ecosystem, compare it against more feature-heavy alternatives before choosing.