Durable Workflow for Laravel
Durable Workflow is the embedded Laravel runtime for durable execution. Write
long-running workflows as ordinary PHP, keep completed work recorded through
worker restarts and application deploys, and use Laravel's queues, cache, and
database as the runtime.
This package also provides the orchestration engine hosted by
Durable Workflow Server. Use the
PHP SDK with Server or
Durable Workflow Cloud when workers need
to run outside the Laravel application or across PHP, Python, and Rust.
Current Workflow requires PHP 8.2 or newer and Laravel 12.72.0 or newer
on the 12.x line, or Laravel 13.41.0 or newer on the 13.x line. Laravel 13
requires PHP 8.3. The dependency security policy
records the supported framework floors. Keep Composer audits and application
security updates enabled.
Upgrade to 2.21
Upgrade PHP 8.1 applications to PHP 8.2 or newer and Laravel 10/11 applications
to patched Laravel 12 or 13 before requiring Workflow 2.21. Composer refuses
2.21 on the retired platforms. Keep the application's existing 2.20.x lock
while preparing that upgrade; older Workflow releases do not extend upstream
security support for PHP or Laravel. Do not disable advisory blocking to force
an upgrade.
This platform change does not migrate durable history. Existing v1 runs remain
owned by v1; retain their code and workers until they finish, and use the
embedded upgrade contract
to choose drain or coexistence. The stable 1.x authority is unchanged.
Laravel 9 applications remain on their compatible Workflow 2.16.x line until
they upgrade the framework. Laravel 9 has no fix for the
TokenGuard advisory
and was removed in Workflow 2.17.0; see #922.
Install
composer require durable-workflow/workflow:^2.0
php artisan migrate
For a new v2-only application, set DW_V1_ENABLED=false before the first
migration. This omits the legacy v1 tables and queue watchdog. Existing
applications keep v1 enabled by default so they can drain older work; do not
disable it until that work is retired. Changing this setting does not drop
existing tables.
Run a Laravel queue worker or Horizon to execute workflows and activities:
php artisan queue:work
With the pcntl extension, a queue worker kills any job that runs longer than
its timeout: the worker's --timeout, 60 seconds by default. A workflow task
killed this way is retried only after its lease expires
(workflows.v2.workflow_task_lease_seconds, 300 seconds by default) and is
counted as a lost lease. A worker that serves the workflow queue logs a warning
when it starts if its timeout is below the lease. Wide all() fan-outs can need
longer than 60 seconds for one workflow task.
Raise --timeout on the workers that serve workflow tasks to cover your
longest workflow task, keeping the queue connection's retry_after above it;
Laravel requires retry_after to exceed every job's timeout. To keep a
bounded timeout for activities, give them their own queue and workers.
Activities run on their workflow's connection and queue unless the activity
class sets $connection or $queue, or the workflow passes ActivityOptions:
// config/queue.php
'redis' => [
'driver' => 'redis',
'connection' => 'default',
'queue' => 'default',
'retry_after' => 330, // above the workflow task worker's --timeout
],
final class ChargeCard extends Activity
{
public ?string $queue = 'activities';
}
php artisan queue:work redis --queue=default --timeout=300 # workflow tasks
php artisan queue:work redis --queue=activities --timeout=60 # activities, bounded
From Workflow 2.34.0, DW_V2_WORKFLOW_TASK_JOB_TIMEOUT_SECONDS can instead give
workflow task jobs their own timeout, which Laravel's worker uses in place of
its --timeout for those jobs, while activities on the same workers keep the
worker's --timeout. It is kept 10 seconds below the connection's
retry_after, so raise retry_after above it. It is unset by default.
If a workflow task loses its lease three times in a row
(DW_V2_WORKFLOW_TASK_LOST_LEASE_ATTENTION_THRESHOLD), the run summary and
describe carry an additive task_attention field, and operator metrics count
it. Set DW_V2_WORKFLOW_TASK_LOST_LEASE_FAIL_RUN=true to fail such a run with a
typed task failure instead; that requires a threshold of at least 2.
For the default database queue on SQLite, failed reservation writes preserve
unclaimed work after a proven rollback. See SQLite queue reservations
for the supported framework versions and custom-connector boundary.
Optional tracing and log correlation
Core 2.9.0 can recover bounded W3C context across embedded queue workers and
add run, task, activity, attempt, trace and span identifiers to Laravel logs.
Tracing is disabled by default and uses the application's OpenTelemetry
provider. See embedded tracing for migrations,
configuration, the log tap, exporter limits and measured overhead.
Your First Workflow
<?php
use Workflow\V2\Activity;
use Workflow\V2\Workflow;
use Workflow\V2\WorkflowStub;
use function Workflow\V2\activity;
final class GreetActivity extends Activity
{
public function handle(string $name): string
{
return "Hello, {$name}!";
}
}
final class GreetWorkflow extends Workflow
{
public function handle(string $name): string
{
return activity(GreetActivity::class, $name);
}
}
$workflow = WorkflowStub::make(GreetWorkflow::class);
$workflow->start('world');
echo $workflow->output(); // Hello, world!
Workflow code can coordinate activities, timers, signals, queries, updates,
child workflows, sagas, cancellation, retries, parallel work, side effects,
continue-as-new, search attributes, memo, and message streams. The runtime
persists execution history so replay can resume after process or host failure
without repeating completed activities.
Schedule a Workflow
use Workflow\V2\Support\ScheduleManager;
$schedule = ScheduleManager::create(
scheduleId: 'daily-greeting',
workflowClass: GreetWorkflow::class,
cronExpression: '0 9 * * *',
arguments: ['world'],
executionTimeoutSeconds: 120,
runTimeoutSeconds: 60,
);
Run php artisan workflow:v2:schedule-tick from Laravel's scheduler to start
due occurrences. Both scheduled occurrences and ScheduleManager::trigger()
use these limits. The execution timeout covers one logical execution across
retries and continue-as-new. The run timeout limits each individual run and
resets on continue-as-new. Each occurrence starts a new execution budget.
Omit either option, or pass null, to leave that limit unset.
See schedule timeout configuration for the action format,
validation and updates.
Choose a Deployment
| Deployment |
Use it when |
Runtime owner |
| Embedded Laravel |
Workflows and activities live inside one Laravel application. |
Your application owns persistence and queue execution. |
| Self-hosted Server |
Workers run independently or in multiple languages. |
Your team operates Server, MySQL, Redis, and optional Waterline. |
| Durable Workflow Cloud |
You want a managed runtime for PHP, Python, and Rust workers. |
Durable Workflow operates the runtime and persistence. |
Embedded runs remain owned by the Laravel application. Moving new work to
Server or Cloud does not reinterpret existing embedded history.
Learn More
Questions and design discussions are welcome in
GitHub Discussions
and Discord.
Sponsors
Durable Workflow is sustained by contributors and sponsors: