- How do I integrate Symfony Workflow into a Laravel app for multi-step order processing?
- Install the package via Composer, publish the config file, and define your workflow in `config/workflow.php` using the `workflow` type for concurrent states (e.g., 'pending', 'review', 'shipped'). Use the `WorkflowTrait` on your Eloquent model to attach the workflow, then trigger transitions via `Workflow::apply($model, 'transition_name')`. Events like `workflow.order.transition.shipped` can fire notifications or jobs.
- What’s the difference between a workflow and a state machine in this package?
- A **workflow** allows multiple concurrent states (e.g., a ticket can be 'open' and 'pending' simultaneously), while a **state machine** enforces a single active state (e.g., order status: 'pending' → 'shipped'). Configure the `type` key in your workflow definition to switch between them. Workflows are ideal for complex processes like content moderation, while state machines suit linear pipelines.
- Does this package support Laravel 13, and what PHP versions are compatible?
- Yes, the latest version (6.x) supports Laravel 10–13 and PHP 8.1–8.4. Check the [README’s version table](https://github.com/zerodahero/laravel-workflow#laravel-support) for exact compatibility. Downgrading to older Laravel versions may require rolling back to an earlier package version (e.g., v5 for Laravel 11). Always test thoroughly after upgrades.
- How do I define guards or validation logic for workflow transitions?
- Guards are defined in your workflow configuration under the `transitions` array using the `guard` key. For example, `guard: 'can_approve'` will call a method on your model or a custom guard service. You can also use Symfony’s `guard` options like `guard_expression` for conditional logic. Combine guards with events to trigger validation or notifications before transitions.
- Can I use this package with non-Eloquent models or API resources?
- While the package is optimized for Eloquent models via `WorkflowTrait`, you can manually attach workflows to any object by instantiating the Symfony `Workflow` class directly. Use the `Workflow` facade or service container to access the workflow instance, then apply transitions via `apply($object, 'transition')`. For API resources, ensure the workflow state is serialized/deserialized correctly in your JSON responses.
- What’s the best way to audit workflow state changes in production?
- Leverage Laravel’s event system to log transitions. Subscribe to events like `workflow.{name}.transition.{transition}` and store the payload (e.g., model ID, old/new states, user) in a separate `workflow_audit` table. Alternatively, use Laravel’s logging channel or third-party packages like `spatie/laravel-activitylog` to track changes. For critical systems, consider database triggers or event sourcing.
- How do I handle failed workflow transitions (e.g., database errors mid-transition)?
- Wrap transition calls in a `try-catch` block to handle exceptions. For idempotency, ensure your event listeners or transition logic are retry-safe. Use Laravel’s `queue` system to defer non-critical transitions (e.g., `Workflow::apply($model, 'transition')->onQueue('workflow-jobs')`). For rollbacks, implement a `revert` transition or use database transactions around critical workflow steps.
- Are there performance considerations for high-traffic workflows?
- Workflow state is stored as a model attribute (default: `marking`), so ensure this column is indexed for large datasets. Cache workflow definitions by instantiating the `Workflow` class once per request (Symfony’s `Workflow` is stateless). For high-throughput systems, consider denormalizing workflow data or using a dedicated marking store (e.g., Redis) via Symfony’s `marking_store` option.
- How do I migrate an existing app to this package without downtime?
- Add the `marking` column to your table first, then backfill existing records with their initial state using a data migration. Use a zero-downtime deployment strategy: deploy the package, then gradually enable workflows for new records. For critical systems, test the migration in staging with production-like data volumes. The package supports downgrades, so rollback plans are straightforward.
- What alternatives exist for Laravel workflows, and when should I choose this package?
- Alternatives include `spatie/laravel-activitylog` (for simple state tracking), `orchid/software/process` (for visual workflows), or rolling your own state machine. Choose this package if you need **Symfony’s battle-tested Workflow component**, support for **complex multi-state processes**, or **deep Laravel integration** (Eloquent, events, service container). It’s ideal for enterprise apps with approval chains, order processing, or content moderation.