Weave Code
Workflow Laravel Package
symfony/workflow
The Symfony Workflow component provides tools for managing workflows and finite state machines in PHP applications, letting you define states, transitions, and guards to model business processes cleanly and reliably.
Provides tools for managing a workflow or finite state machine
Frequently asked questions about Workflow
- How do I install and configure symfony/workflow in Laravel?
- Install it with composer require symfony/workflow, then register a Laravel service provider that binds Workflow or StateMachine instances using your places, transitions, and guards. Define workflow configuration in config files or a dedicated class, and resolve the workflow through Laravel's service container. You will typically create listeners for transition events in EventServiceProvider. This manual wiring is expected because the component is Symfony-native, not a Laravel package.
- Which PHP and Laravel versions does Symfony Workflow support?
- Symfony Workflow 7.x requires PHP 8.2 or newer, while 8.x requires PHP 8.4 or newer, so it fits modern Laravel applications on current PHP releases. Older PHP versions can use 6.x, but you may lose newer features such as BackedEnum support. Pin to a stable minor version like ^8.1 and verify compatibility with your Laravel and Symfony dependencies. This helps avoid surprises during maintenance updates.
- What is the difference between workflow and state machine mode in Symfony Workflow?
- In workflow mode, an object can be in multiple places at the same time, which is useful for processes with parallel states. In state machine mode, exactly one place is active at a time, making it better for simple status transitions like order lifecycles. Both modes support transitions, guards, and events, so choose based on whether your domain needs concurrency. You configure the mode when defining the workflow.
- How do I persist workflow state with Eloquent models?
- Use MethodMarkingStore to read and write the marking through a property or method on your Eloquent model, which keeps state in your existing table. For more advanced persistence, implement a custom marking store backed by an Eloquent table or use a database-backed store if available. DoctrineMarkingStore is database-backed but is Doctrine-oriented and may require a workflow_markings table. Start with MethodMarkingStore to avoid schema changes.
- How do guard conditions work in Symfony Workflow?
- Guards are optional conditions attached to transitions that decide whether the transition is currently allowed. They can be callbacks, expressions, or event listeners that inspect the subject and workflow marking. If a guard returns false, the transition is blocked and the workflow remains unchanged. This keeps business rules declarative instead of scattered across controllers.
- How can I listen to workflow transition events in Laravel?
- Symfony Workflow dispatches events for transitions, including before and after events, and you can map them to Laravel listeners in EventServiceProvider. Listeners receive the transition event payload with the subject, transition, and workflow context, so you can trigger notifications, API calls, or queued jobs. Register listeners carefully to avoid coupling side effects to controllers. This event-driven approach keeps workflow logic decoupled from Laravel-specific code.
- Can Symfony Workflow generate diagrams for documentation?
- Yes, the component can dump the workflow as Graphviz output, and the ecosystem also supports Mermaid diagrams for documentation and debugging. This is useful for stakeholder communication and for validating that places and transitions match the intended process. If labels are generated dynamically, use a recent patch release because v8.1.8 fixes Mermaid label escaping for hash characters. Generate diagrams in CI or an Artisan command to keep docs current.
- Is Symfony Workflow fast enough for production Laravel applications?
- Workflow initialization adds roughly 5 to 10 milliseconds per request, which is usually acceptable but should be measured in your app. For high-throughput systems, use MethodMarkingStore for in-memory marking and cache workflow definitions where possible. Benchmark in staging with realistic request volumes and monitor transition events. Keeping definitions lean and avoiding unnecessary listeners helps control overhead.
- How should I test Symfony Workflow transitions in Laravel?
- Unit test the workflow by constructing it with an in-memory marking store or a simple test subject, then assert enabled transitions, apply allowed transitions, and verify the resulting places. In Laravel feature tests, dispatch the workflow through your service provider and assert that expected events and side effects occur. Cover guard failures and blocked transitions, not just happy paths. This catches state regressions before they reach production.
- When should I use Symfony Workflow instead of spatie/laravel-state-machine?
- Choose Symfony Workflow when you need more than a few states, conditional guards, transition events, auditability, or parallel places in workflow mode. It is a strong fit for complex order processing, SaaS feature rollouts, or approval pipelines with multiple side effects. For simple single-state status fields, spatie/laravel-state-machine may be lighter and faster to adopt. Symfony Workflow has a steeper learning curve but offers more built-in structure and Symfony-backed maintenance.
Weaver
How can I help you explore Laravel packages today?