Laravel Durable Workflow: Long-Running Processes
Table of contents
Every Laravel project I maintain has one of them: a process that is not really a job but a chain of jobs. Generate a file, upload it, notify someone, wait for an approval, then carry on. We usually glue that together with Bus::chain(), a status column and a few if statements, and it works until a worker dies halfway through. Laravel News covered Durable Workflow on November 17, 2026, a free, open-source package that records the progress of these processes in your database so they survive worker restarts and deploys. I read through it with a client order pipeline in mind; here is how it works and where I would use it.
What Durable Workflow actually does
Durable Workflow (durable-workflow/workflow, by Richard McDaniel) splits a long process into two kinds of classes:
- a workflow, which coordinates the steps and decides what happens next;
- activities, which do the actual work: generating a file, calling an API, sending a notification.
The workflow's history is stored in your own database. When a worker picks the workflow up again, after a restart, a deploy or a wait, the package replays the workflow's PHP code and reuses the results it already recorded, so finished activities are not run a second time. It runs inside your application on your own database, queues and cache; there is an optional paid cloud service, but you do not need it.
Installing it in a Laravel 12 or 13 app
The version covered by Laravel News is 2.28.1. The requirements are worth checking before you start:
- Laravel 12.72+ or 13.41+, PHP 8.2+ (PHP 8.3+ on Laravel 13);
- an asynchronous queue connection: database, Redis and Amazon SQS work, the
syncdriver does not; - a cache driver that supports locks.
composer require durable-workflow/workflow:"^2.0"
php artisan migrate
php artisan queue:work
The migrations are loaded automatically, and Horizon works as the worker if you are already on Redis. The generators take a --v2 flag that puts the classes in app/Workflows:
php artisan make:workflow ReportWorkflow --v2
php artisan make:activity GenerateReport --v2
A workflow and its activities
The example in the article is a report pipeline: generate the report, upload it, tell the user. The workflow reads like a plain sequence of calls:
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;
}
}
Each activity is a small class with a handle() method:
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);
}
}
You start it from a controller or a command. start() returns straight away and a queue worker runs the workflow in the background:
use App\Workflows\ReportWorkflow;
use Workflow\V2\WorkflowStub;
$workflow = WorkflowStub::make(ReportWorkflow::class);
$workflow->start($reportId);
What I like is that the order of the steps lives in one method I can read top to bottom, instead of being spread across a chain definition, three jobs and a status column.
The replay rules you must not break
Replay is what makes the package durable, and it comes with two rules that will bite you if you ignore them:
- The workflow must make the same decisions every time it replays. Database reads,
now(), random values and HTTP calls belong in activities, not in the workflow'shandle(). If the workflow reads an order status directly and the status changed between two replays, it can take a different branch than the first time. - Activities should be idempotent. An activity can run more than once if the worker stops after doing the work but before the result is recorded. Upload to a stable storage key, use an idempotency key for payment or email APIs, and check whether the work was already done before doing it again.
The article also warns that changing the code of workflows that are already running needs care, since a replay runs the new code against the old history. On a deploy, I would let running workflows finish, or version the workflow class rather than editing it in place.
Retries, signals and timers
Three features make it more than a nicer job chain:
- Retries are opt-in. In v2 an activity gets one attempt by default; you configure
$triesand abackoff()policy when a step calls something flaky. An unhandled final failure can end the run, and deploying a fix does not reopen it automatically, so plan how you will restart failed runs. - Signals send outside input into a running workflow. The article's example is an approval: the workflow waits for an "approved" signal before running the next activity, with an optional timeout.
- Durable timers let a workflow wait for a set time without holding a worker or a delayed job you have to track yourself.
Signals plus timers cover the processes I usually hand-roll with a pending_approval status and a scheduled command that checks it every five minutes.
When I would use it, and when a job is enough
The article itself says it: for a single background task, a regular Laravel job is still the right tool. I would reach for Durable Workflow when at least one of these is true:
- the process has several steps, and re-running a finished step is expensive or wrong (charging a card, sending an email, calling a rate-limited API);
- the process waits for something outside the code: a human approval, a webhook, a delay of hours or days;
- you need to see where each run is, step by step, without inventing a status table.
On a Magento or Laravel e-commerce stack, order fulfilment with a stock reservation, a payment capture and a carrier label is a good fit. A nightly export that runs in one go is not.
Conclusion
Durable Workflow brings the workflow-and-activities model to a normal Laravel app, on the database, queue and cache you already run. The code stays readable and the progress survives restarts, as long as you keep the workflow deterministic and the activities idempotent. Before adopting it, check the Laravel and PHP version requirements, make sure your queue is not sync in any environment that runs workflows, and start with one process that is causing you pain today. The documentation covers signals, timers and retries in more detail than I did here.