Weave Code
Workflow Laravel Package
symfony/workflow
Symfony Workflow component helps model and run workflows or finite state machines. Define places and transitions, guard rules, events, and marking stores to track state changes and integrate processes cleanly into your application.
Provides tools for managing a workflow or finite state machine
Frequently asked questions about Workflow
- How do I integrate Symfony Workflow into a Laravel app for order processing with states like 'pending', 'approved', and 'shipped'?
- Start by defining your workflow in YAML/XML or PHP using the `Workflow` class. Register it as a service in Laravel’s `AppServiceProvider` and bind it to a model (e.g., `Order`). Use `MethodMarkingStore` for in-memory state or `DoctrineMarkingStore` for database persistence. Trigger transitions via methods like `$order->apply($workflow->getTransition('approve'))`. Laravel’s events can handle side effects (e.g., `OrderShipped` firing a notification).
- What’s the best way to handle conditional transitions (e.g., 'approve' only if user is admin) in Laravel?
- Use Symfony Workflow’s **guards** to enforce conditions. Define them in your workflow file (e.g., `guard: is_admin`) and implement the logic as a callable or service method. Laravel’s service container can inject dependencies (e.g., `Auth` facade) into the guard. Example: `guard: method: checkAdminPermission`. This keeps business logic decoupled from your workflow definition.
- Does Symfony Workflow support multi-tenancy for SaaS applications with tenant-specific workflows?
- Yes, use **dynamic workflow loading** via Laravel’s service container. Bind tenant-specific workflows in a resolver (e.g., `WorkflowResolver`) that fetches configurations from a database or cache. For state storage, use `DoctrineMarkingStore` with a `tenant_id` column to isolate markings per tenant. Example: `$workflow = app('workflow')->get($tenantId, 'order_workflow');`
- How do I visualize workflows for stakeholders or debugging in Laravel?
- Symfony Workflow generates **Mermaid.js diagrams** automatically. Use the `Workflow::getGraph()` method to output the workflow structure, then render it in a Laravel Blade view or API response. For debugging, log transitions with `TraceableWorkflow` or integrate with Laravel’s `debugbar`. Example: `@include('workflow-diagram', ['graph' => $workflow->getGraph()])`
- What’s the performance impact of using Symfony Workflow in a high-traffic Laravel app (e.g., 10K+ orders/day)?
- Workflow initialization adds **~5–10ms per request**, but this is negligible for most apps. For high-throughput systems, use `MethodMarkingStore` (in-memory) or cache workflow definitions. Benchmark in staging with tools like Laravel Debugbar or Blackfire. If using `DoctrineMarkingStore`, ensure your database is optimized (indexes on `markings` table).
- Can I migrate from manual state checks (e.g., `if ($order->status == 'pending')`) to Symfony Workflow incrementally?
- Absolutely. Start with a **single critical workflow** (e.g., order processing) and wrap existing logic in transitions. Use Laravel’s `Artisan` to dump workflows for validation (e.g., `php artisan workflow:dump`). Gradually replace `if-else` blocks with `$workflow->can($transition)` checks. For legacy code, create a facade to abstract the workflow layer.
- How do I trigger Laravel events (e.g., notifications, queues) when a workflow transition occurs?
- Symfony Workflow emits events (e.g., `WorkflowEvent`) that you can map to Laravel’s event system. Subscribe to workflow events in `EventServiceProvider` and dispatch Laravel events. Example: `event(new OrderShipped($order))`. For async tasks, use Laravel Queues inside the event listener. Workflow events also support **payloads** (e.g., transition name, entity) for rich context.
- What PHP versions does Symfony Workflow support, and how does it align with Laravel’s LTS?
- Symfony Workflow **requires PHP 8.2+** (v8.x) or **8.4+** (v9.x), matching Laravel’s LTS roadmap (Laravel 10+). For older PHP (7.4–8.1), use v6.x but note missing features like `BackedEnum` support. Check compatibility with your Laravel version (e.g., Laravel 11 works with Workflow v8.x). Always pin to a minor version (e.g., `^8.0`) in `composer.json` to avoid breaking changes.
- Is there a simpler alternative to Symfony Workflow for basic state machines (e.g., 2–3 states) in Laravel?
- For simple workflows, consider **spatie/laravel-state-machine** or **verot/state-machine**. These are lighter but lack guards, events, and advanced features like `TraceableWorkflow`. Symfony Workflow is overkill for trivial cases but essential for **conditional transitions, multi-tenancy, or audit trails**. Evaluate your needs: if you only need linear states (e.g., `draft → published`), a simpler package may suffice.
- How do I ensure workflow state changes are immutable for compliance (e.g., GDPR, finance)?
- Use Symfony Workflow’s **`TraceableWorkflow`**, which logs every transition with timestamps and metadata. Store markings in a database (e.g., `DoctrineMarkingStore`) and leverage Laravel’s logging/monitoring. For critical apps, add a `workflow_audit` table to track changes. Example: `$traceableWorkflow = new TraceableWorkflow($workflow, new DoctrineMarkingStore());` Combine with Laravel’s `Log::channel('audit')` for centralized tracking.
Weaver
How can I help you explore Laravel packages today?