A workflow is a long-running process on Durable Workflow (durable-workflow/workflow ^2.0, formerly the now-abandoned laravel-workflow/laravel-workflow). It decides when things happen and nothing else: which step runs next, how long to wait, which signal to wait for. Each step that does work is an activity that calls an action, so an operation runs the same whether a controller or a workflow triggers it. This skill holds the decisions made so far; where it is silent, follow the project's own conventions.
Rules
- Reach for a workflow when the process waits. On a signal from outside, or a timer measured in days. Steps that only need to run in order, retry on their own or report progress are a chain or batch of jobs, each calling its action (laravel-jobs).
- A workflow only sequences. What runs when, the waits, the signals. It never writes state, never reads the database to choose its next step, and never decides an outcome. Writes and decisions belong to the actions it runs and, under event sourcing, the aggregate (laravel-event-sourcing), so every business rule lives in one place whichever path triggers the operation.
- Every step that does work is an activity calling one action. The same action a controller would call (laravel-actions). The activity's
handle()takes the workflow's arguments first and the action after them, named after its class; the engine resolves the action from the container. - Ids cross the boundary, and each activity loads its own model. Workflow and activity arguments are plain values: the model's public id,
handle(string $invoiceUuid). Durable Workflow 2.5's codec rejects a model argument withunsupported_value_type, even though its docs say models pass by identifier. The workflow never loads the model itself, because that would be a database read; the activity does, so each step works on the current row. - Under event sourcing, reactors start and signal workflows. A reactor on the stored event that begins the process starts the workflow; a reactor on the event a waiting workflow needs signals it. Starting or signalling a workflow is a side effect, and side effects belong in reactors, which a replay never re-runs.
- Engine mechanics come from the package's docs. Timers, signals, and starting or loading a workflow: read the Durable Workflow docs (durable-workflow.com). The v2 API lives under
Workflow\V2; examples written for the old package don't apply.
Example
The workflow sends a reminder, waits seven days, then issues a final notice:
<?php
declare(strict_types=1);
namespace App\Workflows;
use App\Workflows\Activities\IssueFinalNoticeActivity; use App\Workflows\Activities\RemindInvoiceActivity; use Workflow\V2\Workflow;
use function Workflow\V2\activity; use function Workflow\V2\days;
class CollectInvoicePaymentWorkflow extends Workflow { public function handle(string $invoiceUuid): void { activity(RemindInvoiceActivity::class, $invoiceUuid);
days(7);
activity(IssueFinalNoticeActivity::class, $invoiceUuid);
}
}
Each activity loads the invoice and calls the action it's named after:
```php
<?php
declare(strict_types=1);
namespace App\Workflows\Activities;
use App\Actions\Invoice\RemindInvoiceAction;
use App\Models\Invoice;
use Workflow\V2\Activity;
class RemindInvoiceActivity extends Activity
{
public function handle(string $invoiceUuid, RemindInvoiceAction $remindInvoiceAction): void
{
$remindInvoiceAction(Invoice::query()->where('uuid', $invoiceUuid)->firstOrFail());
}
}
A reactor starts the workflow when the invoice is issued:
<?php
declare(strict_types=1);
namespace App\Reactors;
use App\Events\Invoice\InvoiceIssued;
use App\Workflows\CollectInvoicePaymentWorkflow;
use Spatie\EventSourcing\EventHandlers\Reactors\Reactor;
use Workflow\V2\WorkflowStub;
class InvoiceIssuedReactor extends Reactor
{
public function onInvoiceIssued(InvoiceIssued $event): void
{
WorkflowStub::make(CollectInvoicePaymentWorkflow::class)->start($event->aggregateRootUuid());
}
}
Reach for these when the situation calls for it
A step or reactor whose side effect mustn't run twice. An activity retries after a failure and a queued reactor can be redelivered, so the work behind either can run again. Key the side effect with leeovery/laravel-idempotency. Work that lives in the database, such as recording an event or starting a workflow, goes in Idempotency::once(): it claims the key and runs the work in one transaction, and skips the work when the key is already claimed.
class InvoiceIssuedReactor extends Reactor
{
public function onInvoiceIssued(InvoiceIssued $event): void
{
$invoiceUuid = $event->aggregateRootUuid();
Idempotency::once("invoice:{$invoiceUuid}:collect-payment", function () use ($invoiceUuid): void {
WorkflowStub::make(CollectInvoicePaymentWorkflow::class)->start($invoiceUuid);
});
}
}
An irreversible external effect, such as a send, can't sit in a transaction, so it never goes in once(). Check Idempotency::completed($key), do the work, then call Idempotency::complete($key). A crash between the two repeats the send on the retry instead of losing it.
Anti-patterns
- ❌ Loading the invoice in a workflow's
handle()to checkisPaid(). Whether the final notice still applies is the action's decision. - ❌ A write, a query or a call to a service in a workflow, outside an activity.
- ❌ An activity that does more than load its model and call its action.
- ❌ A model as a workflow or activity argument. The engine rejects it.
- ❌ A workflow for steps that never wait. Chain the jobs.
- ❌ A send or any other external call inside
Idempotency::once(). The rollback can't take it back.
Related
- laravel-event-sourcing — aggregates, events and the reactors that start workflows
- laravel-actions — the operations activities call
- laravel-jobs — chains and batches, for processes that don't wait
- leeovery/laravel-idempotency — idempotency keys for side effects that may run twice