- How do I install and set up zerodahero/laravel-workflow in a Laravel application?
- Install it with composer require zerodahero/laravel-workflow, then publish the config with php artisan vendor:publish --provider="ZeroDaHero\LaravelWorkflow\WorkflowServiceProvider". Define your workflow or state machine in config/workflow.php and attach the package's WorkflowTrait to the Eloquent model you want to manage. If you do not use package discovery, register WorkflowServiceProvider and the Workflow facade manually. This keeps setup declarative and avoids runtime workflow construction.
- Which Laravel and PHP versions does laravel-workflow support?
- The current package line supports Laravel 10 through 13 and PHP 8.1 through 8.4, with v6.3 and v6.4 covering Laravel 13. Older package versions map to older Laravel releases, such as ^4.0 for Laravel 9 and 10 or ^3.2 for Laravel 8. Version 6 dropped PHP 8.0 and Laravel 9 support, so check the support table before upgrading. Pin a compatible major or minor based on your app's Laravel and PHP versions.
- How do I define a workflow or state machine in config/workflow.php?
- Each workflow is keyed by name in config/workflow.php, with a type of workflow or state_machine; workflow is the default if omitted. Workflows support multiple concurrent states, while state machines track a single state, and the marking store defaults to multiple_state. You define places and transitions declaratively, and can set the model property the workflow ties to plus initial_places. The config-driven approach lets you register multiple workflows per model without building them at runtime.
- How do I attach a workflow to an Eloquent model?
- Add the package's WorkflowTrait to the Eloquent model, then use the Workflow facade to retrieve and operate on the configured workflow for that model. State is stored in a model attribute named marking by default, so ensure the model's table has the corresponding column. The package also supports non-Eloquent objects, and a model can have more than one workflow attached. Keep workflow names consistent between the trait usage, facade calls, and config/workflow.php.
- Can laravel-workflow manage multiple simultaneous states?
- Yes. The workflow type supports multiple concurrent states through the marking store, so a model can be in more than one place at once. If you need a single-state lifecycle, such as order status pending to shipped, use the state_machine type instead. Choose the type based on whether your domain allows parallel states or requires exactly one active state. This flexibility covers use cases like content moderation, multi-phase approvals, and order processing.
- What events does laravel-workflow emit and how do I listen to them?
- The package integrates with Laravel's event system and emits Symfony-style dot-notation events such as workflow.{name}.transition.{transition}. You can listen for these events to trigger notifications, logging, validation, or other side effects during transitions. Because the naming differs from Laravel's conventional event names, be careful to register listeners exactly once and match the configured workflow and transition names. Misconfiguration can cause duplicate listeners or missed events, so test event wiring in staging.
- Is laravel-workflow suitable for high-throughput production applications?
- It can be, but plan for the marking column: index it and consider whether the default model attribute storage fits your load. Symfony's Workflow class is stateless, so you can cache workflow definitions or instantiate them once per request where appropriate. If transitions trigger long-running work, dispatch async jobs and make listeners idempotent. Also define retry or rollback strategies for mid-transition database errors and audit state changes through events or a transition history table.
- How do I test workflows and state machines in a Laravel app?
- Because workflows are defined in config and state lives on the model, you can prepare a model with a given marking and assert whether transitions are allowed or applied through the Workflow facade. Use Laravel's event fakes or listeners to assert that the expected workflow dot-notation events fire. Test guards and custom marking stores explicitly if you rely on them. Keep the marking column present in your test database schema so state reads and writes behave like production.
- What changed in laravel-workflow v6.4.0 and should I upgrade?
- v6.4.0 replaced internal getWorkflow() usage with a non-deprecated accessor path (PR #108), clearing a deprecation warning class that could surface under stricter error reporting. It is a low-risk patch bump from 6.3.x, and pinning ^6.4 is recommended for new and existing installs. Upgrading is especially useful if you escalate deprecation warnings in staging or CI. As with any workflow upgrade, run your transition and event tests afterward.
- What are alternatives to zerodahero/laravel-workflow?
- Alternatives include using the Symfony Workflow component directly in Laravel, or implementing a simpler status column with explicit guarded transition methods if you only need a single-state lifecycle. This package is a good fit when you want declarative config/workflow.php definitions, Eloquent integration via WorkflowTrait, and Symfony features like guards and metadata. If you need multiple concurrent states or complex approval flows, a full workflow engine is usually preferable to ad hoc status checks. Evaluate team familiarity with state machines before choosing.