Some background jobs are really several jobs in a row. Generate a report, upload it, then email the customer. Charge a card, reserve stock, then ship. If a queue worker dies halfway, a normal Laravel job has no memory of which steps already finished, so you either redo everything or write your own bookkeeping.
Durable Workflow is a free, open-source Laravel package that does that bookkeeping for you. It records the result of each step in your own database, so a workflow can pick up where it stopped after a restart. Laravel News featured it on 17 November 2026. This tutorial shows how to install it, build a three-step workflow, add retries and wait for a human approval.
Sources: the Laravel News write-up, the durable-workflow/workflow repository and the official docs for options and signals.
How it works
The package splits a process into two kinds of classes:
- Workflow – coordinates the process. It decides which step runs next.
- Activity – does the actual work: generate a file, call an API, send an email.
When an activity succeeds, its result is stored in the database. If the workflow is interrupted, it replays its PHP code on resume and reuses the recorded results instead of running finished activities again.
Everything runs on your own infrastructure: your database stores the history, your Laravel queues run the work and your cache provides locks. There is an optional paid cloud service, but the Laravel package does not need it.
Requirements
According to Laravel News, version 2.28.1 needs:
- Laravel 12.72+ or 13.41+
- PHP 8.2+ (PHP 8.3+ for Laravel 13)
- An asynchronous queue connection (database, Redis, Amazon SQS and so on). The
syncdriver is not supported. - A cache driver that supports locks.
Step 1: Install
composer require durable-workflow/workflow:"^2.0"
php artisan migrate
The package loads its own migrations. Make sure QUEUE_CONNECTION is not sync, then start a worker:
php artisan queue:work
Horizon with Redis works too.
Step 2: Generate a workflow and activities
php artisan make:workflow ReportWorkflow --v2
php artisan make:activity GenerateReport --v2
php artisan make:activity UploadReport --v2
php artisan make:activity NotifyReportReady --v2
The --v2 flag creates v2 classes in app/Workflows.
Step 3: Write the workflow
namespace App\Workflows;
use Workflow\V2\Workflow;
use function Workflow\V2\activity;
final class ReportWorkflow extends Workflow
{
public function handle(int $reportId): string
{
$path = activity(GenerateReport::class, $reportId);
$url = activity(UploadReport::class, $reportId, $path);
activity(NotifyReportReady::class, $reportId, $url);
return $url;
}
}
It reads like normal PHP, but each activity() call is a durable step. If the worker stops after UploadReport finished, the resumed run reuses $path and $url from history and goes straight to the notification.
Step 4: Write an activity
Activities extend Workflow\V2\Activity and implement handle():
namespace App\Workflows;
use App\Services\ReportGenerator;
use Workflow\V2\Activity;
final class GenerateReport extends Activity
{
public function handle(int $reportId): string
{
return app(ReportGenerator::class)->generate($reportId);
}
}
ReportGenerator stands for your own existing service. Return something the next step can use, such as a file path on shared storage.
Step 5: Start it
use App\Workflows\ReportWorkflow;
use Workflow\V2\WorkflowStub;
$workflow = WorkflowStub::make(ReportWorkflow::class);
$workflow->start($reportId);
start() returns immediately. A queue worker runs the workflow in the background, and the final URL becomes the workflow’s output.
Add retries (they are opt-in)
In v2, an activity is attempted once by default. If you want another try after an exception, set $tries and a backoff() policy on the activity:
use Workflow\V2\Activity;
final class UploadReport extends Activity
{
public ?string $queue = 'uploads';
public int $tries = 3;
public function backoff(): array
{
return [5, 30, 120]; // seconds between attempts
}
public function handle(int $reportId, string $path): string
{
return app(\App\Services\ReportUploader::class)->upload($reportId, $path);
}
}
Note that $connection and $queue are declared public ?string, so your override must keep the nullable type. Use null to inherit the application default.
You can also override settings for a single call with ActivityOptions:
use Workflow\V2\Support\ActivityOptions;
use function Workflow\V2\activity;
$receipt = activity(
ChargeCard::class,
new ActivityOptions(queue: 'critical', maxAttempts: 5, startToCloseTimeout: 30),
$orderId,
);
Wait for a human: signals
Signals let outside code push input into a running workflow. A workflow declares the signal with an attribute and waits for it with await():
use Workflow\V2\Attributes\Signal;
use Workflow\V2\Attributes\Type;
use Workflow\V2\Workflow;
use function Workflow\V2\await;
#[Type('order-approval')]
#[Signal('approved-by', [
['name' => 'approvedBy', 'type' => 'string'],
])]
final class OrderApprovalWorkflow extends Workflow
{
public function handle(): array
{
$approvedBy = await('approved-by');
return ['approved_by' => $approvedBy];
}
}
Send the signal from a controller, after you have authenticated and authorised the user:
use Workflow\V2\WorkflowStub;
$result = WorkflowStub::load('order-123')
->attemptSignalWithArguments('approved-by', ['approvedBy' => (string) $user->id]);
$result->accepted(); // true when the signal was durably accepted
The docs are clear that the signal argument is just data. It does not prove who sent it, so your route must do the auth and policy check before signalling. Also, await() belongs in workflows only, never in activities.
Rules that keep replay safe
Replay is what makes the package work, and it comes with a few rules:
- Keep database reads and external calls inside activities. Workflow code must make the same decisions every time it is replayed with the same recorded results.
- Make activities safe to repeat. If a worker finishes an upload but crashes before the result is recorded, that activity can run again. Use stable keys, for example a fixed object-storage path per report.
- Be careful changing running workflows. Old runs replay with the code you deploy, so plan changes to workflow logic with the project’s versioning guidance.
- A final failure ends the run. Deploying a fix does not automatically restart a failed run.
When to use it (and when not)
For a single background task, a normal Laravel job is still the right tool. Durable Workflow makes sense when a process has several steps whose progress must survive restarts, or when it must wait for outside input such as an approval, a webhook or a timer.
Takeaway
Durable Workflow gives Laravel apps durable, multi-step background processes using only the database, queue and cache you already run. Install it, split your process into a workflow plus activities, opt in to retries where they make sense, and keep side effects inside activities so replays stay safe.
