- What is LaraFlow used for in Laravel applications?
- LaraFlow is a state machine and workflow package for Laravel Eloquent models. You map a model column to a set of states and a directed graph of allowed transitions, then move records through controlled paths. It fits bounded per-record lifecycles such as order fulfilment, approval chains, onboarding, subscription dunning, and ticket status management. It is not a BPMN or Temporal-style workflow engine, so parallel states, sagas, and cross-service orchestration are out of scope.
- How do I install and set up szana8/laraflow?
- Install it with Composer using composer require szana8/laraflow, then attach the package trait to your Eloquent model and declare a flow class with states and transitions. Artisan generators are included to reduce the boilerplate for new flows. If you are migrating an existing status column, map its current values to the flow states and route all writes through transitions rather than direct column updates. Verify the composer.json constraints first, because the latest release predates Laravel 11 and 12.
- Does LaraFlow support Laravel 11, Laravel 12, and PHP 8.3 or 8.4?
- The last LaraFlow release was April 2023, which predates Laravel 11 and 12 and PHP 8.3 and 8.4. Check the declared composer.json constraints before committing, and expect that a fork with widened constraints may be required. Because the package is a thin layer over Eloquent and the event dispatcher, patching compatibility is usually a small job. Budget for validating each Laravel major upgrade.
- How do guards, actions, and events work in a LaraFlow transition?
- Guards give you a clean seam for authorization and precondition checks before a transition is allowed, and actions or events handle side effects such as notifications and audit writes. Events let you hook into state changes without putting business rules in controllers. The package description does not specify whether guards run before or inside a transaction, or whether a failed guard throws an exception or returns false, so confirm that contract in the source. Also check whether listeners fire inside or after commit before relying on them for critical side effects.
- Does LaraFlow store transition history for auditing?
- LaraFlow does not appear to include built-in transition history persistence beyond what you add through events. The intended pattern is to listen to the package's transition events and write your own audit records to a table. If you need first-class history, verify whether the package provides it or plan to build an event listener from day one. Confirm the event timing so audit rows stay consistent with the state write.
- How does LaraFlow handle concurrent transitions and database transactions?
- The package description does not specify concurrency handling, so do not assume pessimistic locking or optimistic version checks. Treat the default as last-write-wins unless you verify otherwise in the source. For critical flows, wrap the transition in a database transaction and take a row lock with lockForUpdate before checking and applying the state change. Test concurrent transitions explicitly, because the transactional boundary of the state write plus event dispatch is also unspecified.
- Can LaraFlow handle parallel states, sagas, or workflows across multiple models?
- No. LaraFlow is an in-process, single-model state machine with an enumerated set of states and a directed graph of allowed transitions. It has no parallel states, no compensating actions or sagas, no durable timers, and no cross-service orchestration. Atomically mutating more than one model is not described as a supported pattern, so treat multi-aggregate coordination as out of scope and use a proper workflow engine if you need it.
- Is LaraFlow actively maintained and safe to use in production?
- LaraFlow has 66 stars, a single maintainer, and no release since April 2023, so assume effectively zero upstream support and plan for internal ownership. There is no stated security policy in the available description, so you will need your own advisory response process. The upside is that it is a thin layer over Eloquent, which makes ripping it out and replacing it relatively cheap. Pin versions, review the code, and budget time for Laravel upgrade validation.
- How does LaraFlow compare to spatie/laravel-model-states and asantibanez/laravel-eloquent-state-machines?
- All three add state machine behaviour to Laravel Eloquent models, but Spatie's package and Asantibanez's package are more actively maintained. LaraFlow's differentiators are its declarative class-per-flow design and Artisan generators, which keep business rules out of controllers. Document why you would choose LaraFlow over the alternatives, or pick one of them if maintenance risk matters more. Because the integration surface is small, switching later is a low-cost exercise.
- How do I unit test that a transition is allowed or blocked in LaraFlow?
- The available README excerpt does not list testing utilities, so check the package source for assertion helpers before relying on them. In practice you can call the transition in a test and assert the resulting state, and test guards directly because they are a clean seam for preconditions. For blocked transitions, assert that the state is unchanged and that the expected exception or false return occurs, once you have confirmed the failure contract. If first-class testing helpers are important, compare with Spatie's package before deciding.