Durable Workflow

https://github.com/durable-workflow/workflow
Admin
Durable Workflow is a PHP workflow engine that enables developers to define and manage long-running...
Tokens:224,555
Snippets:1,408
Trust Score:9
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Start a workflow with WorkflowStub::make() and start()

Source: https://github.com/durable-workflow/workflow/wiki/3.-Defining-Workflows-and-Activities

Create a workflow instance with WorkflowStub::make() and call start() to begin execution asynchronously. The start() method returns immediately.

```php
use Workflow\WorkflowStub;

$workflow = WorkflowStub::make(MyWorkflow::class);
$workflow->start();
```

--------------------------------

### Sequence ordering example

Source: https://github.com/durable-workflow/workflow/blob/main/docs/workflow-messages-architecture.md

Illustrates that sequence numbers start at 1 and increment independently per stream.

```text
Stream A: msg_seq_1, msg_seq_2, msg_seq_3
Stream B: msg_seq_1, msg_seq_2, msg_seq_3
```

--------------------------------

### Start and Verify Memcached

Source: https://github.com/durable-workflow/workflow/blob/main/tests/LoadTest/README.md

Commands to start Memcached as a daemon and verify it is running by sending a stats command to the default port.

```bash
# Start Memcached
memcached -d

# Verify
echo "stats" | nc localhost 11211
```

--------------------------------

### Install and set up Laravel Workflow

Source: https://github.com/durable-workflow/workflow/wiki/2.-Installation-and-Setup

Install Laravel Workflow via Composer, publish its migrations, and run the migrations to create the workflows table. Run these commands in order in your Laravel project.

```bash
composer require laravel-workflow/laravel-workflow
```

```bash
php artisan vendor:publish --provider="Workflow\Providers\WorkflowServiceProvider" --tag="migrations"
```

```bash
php artisan migrate
```

--------------------------------

### Set up local development environment

Source: https://github.com/durable-workflow/workflow/blob/main/CONTRIBUTING.md

Clone the main branch and install development dependencies. composer install runs Testbench package discovery automatically; composer build is needed after workbench configuration changes.

```bash
git clone --branch main https://github.com/durable-workflow/workflow.git
cd workflow
composer install
composer build
```

--------------------------------

### Start and Verify Redis Server

Source: https://github.com/durable-workflow/workflow/blob/main/tests/LoadTest/README.md

Commands to start a Redis server and verify it is running. The verification command `redis-cli ping` should return PONG.

```bash
# Start Redis
redis-server

# Verify
redis-cli ping # Should return PONG
```

--------------------------------

### Multi-node Docker Compose setup and run commands

Source: https://github.com/durable-workflow/workflow/blob/main/docs/deployment/multi-node-requirements.md

Docker Compose setup for a multi-node workflow deployment with MySQL and Redis. The YAML defines two application nodes (node-1 and node-2) sharing the same database and cache, plus the commands to start the stack, run migrations on node-1, and follow logs.

```yaml
version: '3.8'

services:
  db:
    image: mysql:8.0
    environment:
      MYSQL_DATABASE: workflows
      MYSQL_ROOT_PASSWORD: secret
    volumes:
      - db_data:/var/lib/mysql
      
  redis:
    image: redis:7-alpine
    volumes:
      - redis_data:/data
      
  node-1:
    build: .
    environment:
      APP_NAME: workflow-node-1
      CACHE_DRIVER: redis
      REDIS_HOST: redis
      DB_HOST: db
      DB_DATABASE: workflows
      DB_USERNAME: root
      DB_PASSWORD: secret
    depends_on:
      - db
      - redis
      
  node-2:
    build: .
    environment:
      APP_NAME: workflow-node-2
      CACHE_DRIVER: redis
      REDIS_HOST: redis
      DB_HOST: db
      DB_DATABASE: workflows
      DB_USERNAME: root
      DB_PASSWORD: secret
    depends_on:
      - db
      - redis

volumes:
  db_data:
  redis_data:
```

```bash
docker-compose up -d
docker-compose exec node-1 php artisan migrate
docker-compose logs -f
```

--------------------------------

### Install and migrate Durable Workflow

Source: https://github.com/durable-workflow/workflow/blob/main/README.md

Install the package and run migrations. For a new v2-only application, set DW_V1_ENABLED=false before the first migration to omit legacy v1 tables and the queue watchdog; existing applications keep v1 enabled by default.

```bash
composer require durable-workflow/workflow:^2.0
php artisan migrate
```

--------------------------------

### Stream key examples

Source: https://github.com/durable-workflow/workflow/blob/main/docs/workflow-messages-architecture.md

Lists example stream keys used to group related messages, including the default instance-level stream and custom streams for approvals, user inboxes, and parent-to-child signals.

```text
"instance:{instance_id}"           - default instance-level stream
"approval_flow:{request_id}"       - custom approval stream
"user_inbox:{user_id}"             - user-specific inbox
"child_signals:{parent_run_id}"    - parent-to-child signals
```

--------------------------------

### Execute activities in series with ActivityStub::make

Source: https://github.com/durable-workflow/workflow/wiki/5.-Concurrent-Activities

Runs three activities sequentially, yielding each promise to wait for completion before starting the next.

```php
use Workflow\ActivityStub;
use Workflow\Workflow;

class MyWorkflow extends Workflow
{
    public function execute()
    {
        return [
            yield ActivityStub::make(MyActivity1::class),
            yield ActivityStub::make(MyActivity1::class),
            yield ActivityStub::make(MyActivity1::class),
        ];
    }
}
```

--------------------------------

### Create and run a first workflow

Source: https://github.com/durable-workflow/workflow/blob/main/README.md

Define an activity and a workflow, then start the workflow and print its output. The runtime persists execution history so replay can resume after process or host failure without repeating completed activities.

```php
<?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!
```

--------------------------------

### Example wake latency output

Source: https://github.com/durable-workflow/workflow/blob/main/tests/LoadTest/README.md

Sample output from a load test showing wake latency percentiles (p50, p95, p99) and other statistics for Redis.

```text
=== Redis Results ===
  p50: 2.15ms
  p95: 5.32ms
  p99: 8.41ms
  mean: 2.89ms
  min: 0.52ms
  max: 12.33ms
  samples: 100
```

--------------------------------

### Deploy to first node (canary) commands

Source: https://github.com/durable-workflow/workflow/blob/main/docs/deployment/multi-node-requirements.md

Deployment commands for the first node (canary) in a zero-downtime deployment. Includes pulling code, installing dependencies, running migrations, and caching config, routes, and views.

```bash
git pull origin main
composer install --no-dev --optimize-autoloader
php artisan migrate --force
php artisan config:cache
php artisan route:cache
php artisan view:cache
```

--------------------------------

### Example throughput output

Source: https://github.com/durable-workflow/workflow/blob/main/tests/LoadTest/README.md

Sample output from a high concurrency load test showing signals per second, total signals, and duration.

```text
=== Redis (High Concurrency) Results ===
  signals/sec: 12450
  total signals: 500
  duration: 0.04s
```

--------------------------------

### GET /api/deployments/{name}

Source: https://github.com/durable-workflow/workflow/blob/main/docs/architecture/worker-deployment.md

Fetches a single deployment by name (namespace/task_queue@build_id).

```APIDOC
## GET /api/deployments/{name}

### Description
Fetches a single deployment by name (namespace/task_queue@build_id).

### Method
GET

### Endpoint
/api/deployments/{name}

### Parameters
#### Path Parameters
- **name** (string) - Required - The deployment name in the format `namespace/task_queue@build_id`.

### Response
#### Success Response (200)
- **deployment** (object) - The deployment object.

#### Response Example
{
  "deployment": {}
}
```

--------------------------------

### Configure file cache for single-node deployment

Source: https://github.com/durable-workflow/workflow/blob/main/docs/long-poll-coordination.md

Laravel config/cache.php example setting the default cache driver to 'file'. Acceptable for single-node deployments because wake signals propagate within the node.

```php
'default' => env('CACHE_DRIVER', 'file'),
```

--------------------------------

### GET /api/deployments

Source: https://github.com/durable-workflow/workflow/blob/main/docs/architecture/worker-deployment.md

Lists every deployment in the namespace, projected from the rollout table plus the live fleet snapshot.

```APIDOC
## GET /api/deployments

### Description
Lists every deployment in the namespace, projected from the rollout table plus the live fleet snapshot.

### Method
GET

### Endpoint
/api/deployments

### Response
#### Success Response (200)
- **deployments** (array) - List of deployment objects.

#### Response Example
{
  "deployments": []
}
```

--------------------------------

### Version Stamp Format Example

Source: https://github.com/durable-workflow/workflow/blob/main/docs/long-poll-coordination.md

Shows the format of version stamps used in cache channels: a microsecond timestamp and ULID combined for uniqueness across nodes.

```text
Format: {timestamp}:{ulid}
Example: 1713216000.123456:01HW8XQZF9P2K3M4N5Q6R7S8T9
```

--------------------------------

### CI workflow step for load tests

Source: https://github.com/durable-workflow/workflow/blob/main/tests/LoadTest/README.md

Add this step to .github/workflows/tests.yml to run load tests in CI. It starts the test environment with docker-compose, executes PHPUnit with the 'load' group, and then tears down the environment.

```yaml
- name: Run load tests
  run: |
    docker-compose -f docker-compose.test.yml up -d
    vendor/bin/phpunit --group=load
    docker-compose -f docker-compose.test.yml down
```

--------------------------------

### Resolve Child References

Source: https://github.com/durable-workflow/workflow/blob/main/docs/architecture/workflow-child-calls-architecture.md

Updates child call with resolved instance/run IDs after child starts. Sets resolved_child_instance_id and resolved_child_run_id, transitions status from Scheduled to Started, and records start timestamp.

```php
public function resolveChildReferences(
    WorkflowChildCall $childCall,
    string $childInstanceId,
    string $childRunId,
): void
```

--------------------------------

### Configure Redis cache store for multi-node wake acceleration

Source: https://github.com/durable-workflow/workflow/blob/main/docs/long-poll-coordination.md

Laravel config/cache.php example setting Redis as the default cache driver with a dedicated connection and lock connection. Point every node at the same Redis instance so wake signals propagate across nodes.

```php
'default' => env('CACHE_DRIVER', 'redis'),

'stores' => [
    'redis' => [
        'driver' => 'redis',
        'connection' => 'cache',
        'lock_connection' => 'default',
    ],
],
```

--------------------------------

### Legal state transitions for ServiceCallStatus

Source: https://github.com/durable-workflow/workflow/blob/main/docs/architecture/workflow-service-calls-architecture.md

ASCII diagram showing the legal transitions between ServiceCallStatus values. Pending can resolve to Accepted, or fail/cancel. Accepted can start, fail, or cancel. Started can complete, fail, or cancel. Terminal states (Completed, Failed, Cancelled) never change.

```text
    [Pending] ──resolved──> [Accepted] ──started──> [Started]
        │                       │                       │
        │                       │                       ├── markCompleted ─> [Completed]
        │                       │                       ├── markFailed ────> [Failed]
        │                       │                       └── markCancelled ─> [Cancelled]
        │                       ├── markFailed ────> [Failed]
        │                       └── markCancelled ─> [Cancelled]
        ├── markFailed ────> [Failed]
        └── markCancelled ─> [Cancelled]
```

--------------------------------

### Retrieve workflow output with output()

Source: https://github.com/durable-workflow/workflow/wiki/3.-Defining-Workflows-and-Activities

After a workflow completes, call output() to get the result data.

```php
$workflow->output();
```

--------------------------------

### Fix Redis not available

Source: https://github.com/durable-workflow/workflow/blob/main/tests/LoadTest/README.md

Use when the load test suite reports 'Redis not available'. First verify Redis is running with redis-cli ping; if it is not, start it with redis-server.

```bash
# Check Redis running
redis-cli ping

# If not running
redis-server
```

--------------------------------

### Find Open Children with ChildCallService::getOpenChildren

Source: https://github.com/durable-workflow/workflow/blob/main/docs/architecture/workflow-child-calls-architecture.md

Returns children in Scheduled or Started states, ordered by sequence.

```php
$openChildren = ChildCallService::getOpenChildren($parentRun);
```

--------------------------------

### Local Docker environment for load tests

Source: https://github.com/durable-workflow/workflow/blob/main/tests/LoadTest/README.md

Provides an isolated Docker environment for load testing. The docker-compose.test.yml defines Redis, Memcached, and MySQL services; the commands start the services, run the load test group, and tear down the environment.

```yaml
# docker-compose.test.yml
version: '3.8'

services:
  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
      
  memcached:
    image: memcached:1.6-alpine
    ports:
      - "11211:11211"
      
  mysql:
    image: mysql:8.0
    environment:
      MYSQL_ROOT_PASSWORD: secret
      MYSQL_DATABASE: testing
    ports:
      - "3306:3306"
```

```bash
docker-compose -f docker-compose.test.yml up -d
vendor/bin/phpunit --group=load
docker-compose -f docker-compose.test.yml down
```

--------------------------------

### Peek and receive messages with MessageService

Source: https://github.com/durable-workflow/workflow/blob/main/docs/workflow-messages-architecture.md

Use peekMessages() and receiveMessages() to get unconsumed inbound messages for a run and stream key. Both are read-only: they do not mark messages consumed or advance the cursor. Cursor movement only happens through consumeMessage() or consumeMessages().

```php
$messages = $messageService->peekMessages($run, $streamKey);
$messages = $messageService->receiveMessages($run, $streamKey);
```

--------------------------------

### Fix Memcached not available

Source: https://github.com/durable-workflow/workflow/blob/main/tests/LoadTest/README.md

Use when the load test suite reports 'Memcached not available'. Check if Memcached is listening on port 11211 with nc; if not, start it in daemon mode with memcached -d.

```bash
# Check Memcached running
echo "stats" | nc localhost 11211

# If not running
memcached -d
```

--------------------------------

### Orchestrate serial and parallel activities with ActivityStub

Source: https://github.com/durable-workflow/workflow/wiki/9.-How-It-Works

Defines a workflow that yields serial activities and a parallel group. The workflow suspends on each yield until the activity completes, and ActivityStub::all runs the parallel activities concurrently. This example demonstrates the core orchestration pattern for Laravel Workflow.

```php
use Workflow\ActivityStub;
use Workflow\Workflow;

class MyWorkflow extends Workflow
{
    public function execute()
    {
        return [
            yield ActivityStub::make(TestActivity::class),
            yield ActivityStub::make(TestOtherActivity::class),
            yield ActivityStub::all([
                ActivityStub::make(TestParallelActivity::class),
                ActivityStub::make(TestParallelOtherActivity::class),
            ]),
        ];
    }
}
```

--------------------------------

### Pause workflow until signal with WorkflowStub::await()

Source: https://github.com/durable-workflow/workflow/wiki/4.-Features

Use WorkflowStub::await() to pause execution until a condition is met. The example waits until the $ready property becomes true. This method should only be used in a workflow, not in an activity.

```php
use Workflow\Workflow;
use Workflow\WorkflowStub;

class MyWorkflow extends Workflow
{
    private bool $ready = false;

    public function execute()
    {
        yield WorkflowStub::await(fn () => $this->ready);
    }
}
```

--------------------------------

### Trigger signal to resume awaitWithTimeout

Source: https://github.com/durable-workflow/workflow/wiki/4.-Features

External code can signal the workflow to resume before the timeout. This example shows calling the signal method without arguments.

```php
$workflow->setReady();
```

--------------------------------

### Inherit memos from parent run with inheritFromParent

Source: https://github.com/durable-workflow/workflow/blob/main/docs/workflow-memos-architecture.md

Copies all parent memos to a child run during continue-as-new. Inherited memos are marked with inherited_from_parent = true and get a new upserted_at_sequence in the child's history. The child can override inherited memos, which clears the inherited flag.

```php
$service->inheritFromParent($parentRun, $childRun, $childStartSequence);
```

--------------------------------

### WorkflowChildCall State Checks

Source: https://github.com/durable-workflow/workflow/blob/main/docs/architecture/workflow-child-calls-architecture.md

Provides methods to check the state of a child call: isOpen() returns true if the state is Scheduled or Started, isTerminal() returns true for any terminal state, and isResolved() returns true if a resolved_child_instance_id is set.

```php
public function isOpen(): bool      // Scheduled or Started
public function isTerminal(): bool  // Any terminal state
public function isResolved(): bool  // Has resolved_child_instance_id
```

--------------------------------

### resolveChildReferences

Source: https://github.com/durable-workflow/workflow/blob/main/docs/architecture/workflow-child-calls-architecture.md

Updates a child call with resolved instance and run IDs after the child starts. This method transitions the child call from Scheduled to Started state.

```APIDOC
## resolveChildReferences

### Description
Updates child call with resolved instance/run IDs after child starts.

### Method
resolveChildReferences

### Signature
```php
public function resolveChildReferences(
    WorkflowChildCall $childCall,
    string $childInstanceId,
    string $childRunId,
): void
```

### Parameters
- `$childCall` (WorkflowChildCall) - Required - The child call record to update
- `$childInstanceId` (string) - Required - The resolved child instance ID
- `$childRunId` (string) - Required - The resolved child run ID

### Returns
- void

### Side Effects
- Sets `resolved_child_instance_id`
- Sets `resolved_child_run_id`
- Transitions status from `Scheduled` → `Started`
- Records start timestamp
```

--------------------------------

### Verify Cache Backend with cache()->put/get

Source: https://github.com/durable-workflow/workflow/blob/main/docs/long-poll-coordination.md

Verifies that the shared cache backend is working after configuration. Run this in a tinker session to confirm that values can be written and read, ensuring all nodes observe the same wake signals.

```php
cache()->put('test', 'value'); cache()->get('test')
```

--------------------------------

### Run Cache Table Migration

Source: https://github.com/durable-workflow/workflow/blob/main/tests/LoadTest/README.md

Commands to create the cache table migration and run migrations for the database cache backend.

```bash
php artisan cache:table
php artisan migrate
```

--------------------------------

### Configure Activity Options with $tries, $timeout, $connection, and backoff()

Source: https://github.com/durable-workflow/workflow/wiki/6.-Workflow-and-Activity-Options

Defines an activity class with configurable retry, timeout, connection, and queue options. The $tries property defaults to 0 (retry forever), $timeout defaults to 0 (no timeout), and $connection defaults to 'default'. The backoff() method returns an array of delays in seconds for retry backoff.

```php
use Workflow\Activity;

class MyActivity extends Activity
{
    public $tries = 0;
    public $timeout = 0;
    public $connection = 'default';
    public $queue = 'default';

    public function backoff()
    {
        return [1, 2, 5, 10, 15, 30, 60, 120];
    }
}
```

--------------------------------

### POST /api/deployments/{name}/promote

Source: https://github.com/durable-workflow/workflow/blob/main/docs/architecture/worker-deployment.md

Promotes the named deployment after consulting the lifecycle plan.

```APIDOC
## POST /api/deployments/{name}/promote

### Description
Promotes the named deployment after consulting the lifecycle plan.

### Method
POST

### Endpoint
/api/deployments/{name}/promote

### Parameters
#### Path Parameters
- **name** (string) - Required - The deployment name in the format `namespace/task_queue@build_id`.

### Response
#### Success Response (200)
- **deployment** (object) - The new deployment shape.

#### Error Response (409)
- **blockages** (array) - Full list of blockages preventing the transition.

#### Response Example
{
  "deployment": {}
}
```

--------------------------------

### Create worker session and schedule activity

Source: https://github.com/durable-workflow/workflow/blob/main/docs/architecture/worker-sessions.md

Creates a worker session handle with Workflow::workerSession() and schedules an activity through it. The options specify the queue, GPU requirements, lease and TTL durations, and concurrency limit.

```php
use Workflow\V2\Support\WorkerSessionOptions;
use Workflow\V2\Workflow;

$session = Workflow::workerSession(
    'gpu-render',
    new WorkerSessionOptions(
        queue: 'gpu-activities',
        requirements: ['gpu:nvidia-l4'],
        leaseSeconds: 120,
        ttlSeconds: 1800,
        maxConcurrentActivities: 1,
    ),
);

$result = $session->activity(RenderFramesActivity::class, $videoId);
```

--------------------------------

### Pre-deployment validation commands

Source: https://github.com/durable-workflow/workflow/blob/main/docs/deployment/multi-node-requirements.md

Pre-deployment validation steps: check database connectivity with migrate:status and cache connectivity using tinker, including a cache put/get test.

```bash
# Verify database connectivity
php artisan migrate:status

# Verify cache connectivity
php artisan tinker
>>> cache()->put('deploy-test', time());
>>> cache()->get('deploy-test');
```

--------------------------------

### WorkflowMemo model class definition

Source: https://github.com/durable-workflow/workflow/blob/main/docs/workflow-memos-architecture.md

Model for workflow memos with methods to get and set JSON values, and static validators for total size and count limits per run.

```php
class WorkflowMemo extends Model
{
    // Get JSON value
    public function getValue(): mixed;
    
    // Set JSON value with size validation
    public function setValue(mixed $value): void;
    
    // Validate total size across all memos for a run
    public static function validateTotalSize(string $runId): void;
    
    // Validate count limit for a run
    public static function validateCount(string $runId): void;
}
```

--------------------------------

### Define a workflow class with execute()

Source: https://github.com/durable-workflow/workflow/wiki/3.-Defining-Workflows-and-Activities

Workflows extend Workflow and implement execute(). Use yield ActivityStub::make() to run an activity and wait for its result.

```php
use Workflow\ActivityStub;
use Workflow\Workflow;

class MyWorkflow extends Workflow
{
    public function execute()
    {
        $result = yield ActivityStub::make(MyActivity::class);

        return $result;
    }
}
```

--------------------------------

### Execute activities in parallel with ActivityStub::all

Source: https://github.com/durable-workflow/workflow/wiki/5.-Concurrent-Activities

Runs three activities concurrently, waiting for all to complete and collecting results.

```php
use Workflow\ActivityStub;
use Workflow\Workflow;

class MyWorkflow extends Workflow
{
    public function execute()
    {
        return yield ActivityStub::all([
            ActivityStub::make(MyActivity1::class),
            ActivityStub::make(MyActivity2::class),
            ActivityStub::make(MyActivity3::class),
        ]);
    }
}
```

--------------------------------

### Count ready tasks by queue

Source: https://github.com/durable-workflow/workflow/blob/main/docs/deployment/multi-node-requirements.md

Run this query to count tasks stuck in the 'ready' state, grouped by queue. Use it to verify that all nodes are polling and to identify queues with backlog.

```sql
-- Count ready tasks by queue
SELECT queue, COUNT(*) 
FROM workflow_tasks 
WHERE status = 'ready' 
GROUP BY queue;
```

--------------------------------

### Call local activity via static Workflow facade

Source: https://github.com/durable-workflow/workflow/blob/main/docs/architecture/local-activities.md

Calls the same local activity primitive through the static workflow facade. Both methods are equivalent and accept the activity class and arguments.

```php
$result = Workflow::localActivity(SendShortNotification::class, $recipientId);
$result = Workflow::executeLocalActivity(SendShortNotification::class, $recipientId);
```

--------------------------------

### WorkflowRunSummary projection class definition

Source: https://github.com/durable-workflow/workflow/blob/main/docs/workflow-memos-architecture.md

Projection model for workflow run summaries, exposing a memo relationship and a method to get memos from the typed v2 contract. Explicitly notes that memos are not filterable and there is no scopeWithMemo() method.

```php
class WorkflowRunSummary extends Model
{
    // Memo relationship (no filtering scope)
    public function memos(): HasMany;
    
    // Get memos from the typed v2 contract
    public function getMemos(): array;
    
    // Note: NO scopeWithMemo() method
    // Memos are not filterable by contract
}
```

--------------------------------

### POST /api/deployments/{name}/resume

Source: https://github.com/durable-workflow/workflow/blob/main/docs/architecture/worker-deployment.md

Moves a Draining deployment back to Active.

```APIDOC
## POST /api/deployments/{name}/resume

### Description
Moves a Draining deployment back to Active.

### Method
POST

### Endpoint
/api/deployments/{name}/resume

### Parameters
#### Path Parameters
- **name** (string) - Required - The deployment name in the format `namespace/task_queue@build_id`.

### Response
#### Success Response (200)
- **deployment** (object) - The new deployment shape.

#### Error Response (409)
- **blockages** (array) - Full list of blockages preventing the transition.

#### Response Example
{
  "deployment": {}
}
```

--------------------------------

### Publish workflow config file

Source: https://github.com/durable-workflow/workflow/wiki/6.-Workflow-and-Activity-Options

Run this artisan command to create a workflows.php configuration file in your config folder.

```bash
php artisan vendor:publish --provider="Workflow\Providers\WorkflowServiceProvider" --tag="config"
```

--------------------------------

### handleRequestCancel: Request graceful cancellation

Source: https://github.com/durable-workflow/workflow/blob/main/docs/architecture/workflow-child-calls-architecture.md

Sets metadata flags for a graceful cancellation request and increments the cancel_requested stats counter. The actual cancellation command is dispatched by WorkflowExecutor, and the child status remains 'Started' until cancellation completes.

```php
private function handleRequestCancel(WorkflowChildCall $childCall, array &$stats): void
{
    $childCall->forceFill([
        'metadata' => array_merge($childCall->metadata ?? [], [
            'parent_close_cancel_requested' => true,
            'parent_close_cancel_requested_at' => now()->toIso8601String(),
        ]),
    ])->save();
    
    $stats['cancel_requested']++;
    // Actual cancel command dispatched by WorkflowExecutor
}
```

--------------------------------

### Using MessageStream from workflow and runtime code

Source: https://github.com/durable-workflow/workflow/blob/main/docs/workflow-messages-architecture.md

Shows how to open a MessageStream from workflow code using the inbox helper and from runtime code using MessageService::stream. The stream is bound to one WorkflowRun and one stream_key. receiveOne() is receive(1).

```php
// From workflow code:
$messages = $this->inbox('chat')->peek();
$message = $this->inbox('chat')->receiveOne();

// From runtime/control-plane code that already owns a run:
$stream = app(MessageService::class)->stream($run, 'chat', $historySequence);
$stream->sendReference(
    targetInstanceId: $targetInstanceId,
    payloadReference: $payloadReference,
    correlationId: $requestId,
);
```

--------------------------------

### Monitor workflow status with running()

Source: https://github.com/durable-workflow/workflow/wiki/3.-Defining-Workflows-and-Activities

Call running() in a loop to wait until the workflow completes or fails. Returns true while running, false otherwise.

```php
while ($workflow->running());
```

--------------------------------

### WorkflowSearchAttribute model interface

Source: https://github.com/durable-workflow/workflow/blob/main/docs/search-attributes-architecture.md

Defines the model methods for getting typed values, setting typed values with coercion/validation or automatic type inference, inferring type from a PHP value, and validating total size and count limits for a run.

```php
class WorkflowSearchAttribute extends Model
{
    // Get typed value (regardless of storage column)
    public function getValue(): mixed;
    
    // Set typed value with coercion and validation
    public function setTypedValue(mixed $value, string $type): void;
    
    // Set typed value with automatic type inference
    public function setTypedValueWithInference(mixed $value): void;
    
    // Infer type from PHP value
    public static function inferType(mixed $value): string;
    
    // Validate total size across all attributes for a run
    public static function validateTotalSize(string $runId): void;
    
    // Validate count limit for a run
    public static function validateCount(string $runId): void;
}
```

--------------------------------

### Fix missing cache table

Source: https://github.com/durable-workflow/workflow/blob/main/tests/LoadTest/README.md

Run when database cache tests fail with 'SQLSTATE[42S02]: Base table or view not found: 'cache''. Creates the cache table and runs migrations for the testing environment.

```bash
php artisan cache:table
php artisan migrate --env=testing
```

--------------------------------

### Run all load tests

Source: https://github.com/durable-workflow/workflow/blob/main/tests/LoadTest/README.md

Executes the entire load test suite using PHPUnit's load group.

```bash
vendor/bin/phpunit --group=load
```

--------------------------------

### Check Timing Hints in workflow_run_summaries

Source: https://github.com/durable-workflow/workflow/blob/main/docs/long-poll-coordination.md

Checks whether timing hints are populated for a workflow run. If all columns are NULL, timing hints are not populated, which is expected for closed runs.

```sql
SELECT next_task_at, next_task_lease_expires_at, wait_deadline_at 
FROM workflow_run_summaries 
WHERE id = '<run_id>';
```

--------------------------------

### Run load tests for a specific backend

Source: https://github.com/durable-workflow/workflow/blob/main/tests/LoadTest/README.md

Runs load tests filtered by backend: Redis, Database, or Memcached. Each command targets a specific test method.

```bash
# Redis only
vendor/bin/phpunit --filter=it_measures_redis
```

```bash
# Database only
vendor/bin/phpunit --filter=it_measures_database
```

```bash
# Memcached only
vendor/bin/phpunit --filter=it_measures_memcached
```

--------------------------------

### Transfer child calls to continued run in PHP

Source: https://github.com/durable-workflow/workflow/blob/main/docs/architecture/workflow-child-calls-architecture.md

Transfers open child calls (Scheduled, Started) from the closing run to the continued run within a database transaction. Terminal children remain with the closing run for historical record. Uses WorkflowChildCall model and ChildCallStatus enum.

```php
public function transferChildCallsToContinuedRun(
    WorkflowRun $closingRun,
    WorkflowRun $continuedRun,
): void {
    DB::transaction(function () use ($closingRun, $continuedRun): void {
        // Transfer open children to new run
        WorkflowChildCall::where('parent_workflow_run_id', $closingRun->id)
            ->whereIn('status', [
                ChildCallStatus::Scheduled->value,
                ChildCallStatus::Started->value,
            ])
            ->update([
                'parent_workflow_run_id' => $continuedRun->id,
                'updated_at' => now(),
            ]);
        
        // Terminal children remain with closing run (historical record)
    });
}
```

--------------------------------

### Test wake-acceleration with CacheLongPollWakeStore

Source: https://github.com/durable-workflow/workflow/blob/main/docs/deployment/multi-node-requirements.md

Use this tinker session to test wake-acceleration coordination between nodes. On Node 1, create a wake signal; on Node 2, verify the signal is received by checking that `changed()` returns true. This helps diagnose long-poll timeout delays.

```bash
# Node 1: Create wake signal
php artisan tinker
>>> app('Workflow\V2\Support\CacheLongPollWakeStore')->signal('test-channel');

# Node 2: Check signal received
>>> $store = app('Workflow\V2\Support\CacheLongPollWakeStore');
>>> $before = $store->snapshot(['test-channel']);
>>> # (Node 1 signals again)
>>> $store->changed($before); // Should return true
```

--------------------------------

### Resume a failed workflow with WorkflowStub::load and resume

Source: https://github.com/durable-workflow/workflow/wiki/7.-Failures-and-Recovery

Loads a workflow by ID and calls resume() to re-execute failed activities. Use after fixing the underlying error.

```php
use Workflow\WorkflowStub;

$workflow = WorkflowStub::load($workflowId);
$workflow->resume();
```

--------------------------------

### Run unit, feature, and full test suites

Source: https://github.com/durable-workflow/workflow/blob/main/CONTRIBUTING.md

Run PHPUnit tests through Orchestra Testbench. Use focused suites while developing, then run the broader suite when the change can affect it. composer coverage generates the unit-test coverage report when Xdebug is available.

```bash
composer unit
composer feature
composer test
```

--------------------------------

### Define an activity class with execute()

Source: https://github.com/durable-workflow/workflow/wiki/3.-Defining-Workflows-and-Activities

Activities extend Activity and implement execute(). The method performs a specific task and returns a result.

```php
use Workflow\Activity;

class MyActivity extends Activity
{
    public function execute()
    {
        // Perform some work...
        return $result;
    }
}
```

--------------------------------

### Query a workflow instance

Source: https://github.com/durable-workflow/workflow/wiki/4.-Features

Call the query method on the workflow instance to retrieve state. Querying does not advance workflow execution.

```php
use Workflow\WorkflowStub;

$workflow = WorkflowStub::make(MyWorkflow::class);

$state = $workflow->getState();
```

--------------------------------

### Database Cache Environment Configuration

Source: https://github.com/durable-workflow/workflow/blob/main/tests/LoadTest/README.md

Environment configuration for the database cache driver, specifying MySQL connection details and the testing database.

```env
CACHE_DRIVER=database
DB_CONNECTION=mysql
DB_HOST=localhost
DB_DATABASE=testing
```

--------------------------------

### Invoke local activity with LocalActivityOptions

Source: https://github.com/durable-workflow/workflow/blob/main/docs/architecture/local-activities.md

Invokes a local activity using the functional API. The options object configures retry and timeout behavior; routing options like connection, queue, worker-session, and schedule-to-start are intentionally rejected.

```php
use Workflow\V2\Support\LocalActivityOptions;
use function Workflow\V2\localActivity;

$result = localActivity(
    SendShortNotification::class,
    new LocalActivityOptions(
        maxAttempts: 3,
        startToCloseTimeout: 10,
        scheduleToCloseTimeout: 30,
        heartbeatTimeout: 5,
    ),
    $recipientId,
);
```

--------------------------------

### Check Cache Store with php artisan tinker

Source: https://github.com/durable-workflow/workflow/blob/main/docs/long-poll-coordination.md

Use this command to inspect the active cache store in a Laravel application. If the output shows `Illuminate\Cache\FileStore`, the file cache cannot propagate wake signals across nodes, which may cause high latency in multi-node deployments.

```bash
php artisan tinker
>>> cache()->getStore()
```

--------------------------------

### Check Wake Signals in Cache

Source: https://github.com/durable-workflow/workflow/blob/main/docs/long-poll-coordination.md

Checks whether wake signals are present in the cache. For Redis, use `redis-cli KEYS "workflow-tasks:*"`; for a database cache, run the SQL query. If no keys are found, wake signals are not firing, so check observer registration.

```bash
redis-cli KEYS "workflow-tasks:*"
```

```sql
SELECT * FROM cache WHERE key LIKE 'workflow-tasks:%';
```

--------------------------------

### Run a single load test

Source: https://github.com/durable-workflow/workflow/blob/main/tests/LoadTest/README.md

Runs a specific load test method by specifying the file and test name.

```bash
vendor/bin/phpunit tests/LoadTest/LongPollCoordinationLoadTest.php::it_measures_redis_backend_wake_latency
```

--------------------------------

### SQL: Create order_read_models table

Source: https://github.com/durable-workflow/workflow/blob/main/docs/architecture/business-reporting-read-models.md

Defines the app read-model table for order milestones. Uses order_id as primary key and stores workflow_id, run_id, status, payment_status, last_milestone, and timestamps.

```sql
CREATE TABLE order_read_models (
    order_id VARCHAR(64) PRIMARY KEY,
    workflow_id VARCHAR(191) NOT NULL,
    run_id VARCHAR(26) NOT NULL,
    status VARCHAR(64) NOT NULL,
    payment_status VARCHAR(64) NOT NULL,
    last_milestone VARCHAR(64) NOT NULL,
    last_milestone_at TIMESTAMP(6) NOT NULL,
    updated_at TIMESTAMP(6) NOT NULL
);
```

--------------------------------

### Mix serial and parallel activity execution

Source: https://github.com/durable-workflow/workflow/wiki/5.-Concurrent-Activities

Combines sequential and parallel execution: activities 1-3 run in series, then 4-5 in parallel, then 6 last.

```php
use Workflow\ActivityStub;
use Workflow\Workflow;

class MyWorkflow extends Workflow
{
    public function execute()
    {
        return [
            yield ActivityStub::make(MyActivity1::class),
            yield ActivityStub::make(MyActivity2::class),
            yield ActivityStub::make(MyActivity3::class),
            yield ActivityStub::all([
                ActivityStub::make(MyActivity4::class),
                ActivityStub::make(MyActivity5::class),
            ]),
            yield ActivityStub::make(MyActivity6::class),
        ];
    }
}
```

--------------------------------

### PHP: Protect cleanup with cancellationShield in finally

Source: https://github.com/durable-workflow/workflow/blob/main/docs/architecture/cancellation-scope.md

Use cancellationShield to defer a newly arriving cooperative request while cleanup is in progress. The cleanup activity runs with ordinary durable retries and can wait on a timer. A successful cleanup closes the run as cancelled; an unhandled failure leaves a failed run.

```php
try {
    timer(3600);
} finally {
    cancellationShield(static function () use ($reservationId): void {
        activity(ReleaseReservationActivity::class, $reservationId);
    });
}
```

--------------------------------

### POST /api/deployments/{name}/rollback

Source: https://github.com/durable-workflow/workflow/blob/main/docs/architecture/worker-deployment.md

Surrenders the promoted slot.

```APIDOC
## POST /api/deployments/{name}/rollback

### Description
Surrenders the promoted slot.

### Method
POST

### Endpoint
/api/deployments/{name}/rollback

### Parameters
#### Path Parameters
- **name** (string) - Required - The deployment name in the format `namespace/task_queue@build_id`.

### Response
#### Success Response (200)
- **deployment** (object) - The new deployment shape.

#### Error Response (409)
- **blockages** (array) - Full list of blockages preventing the transition.

#### Response Example
{
  "deployment": {}
}
```

--------------------------------

### Repeated Human-Input Loop with receiveMessages and waitForCondition

Source: https://github.com/durable-workflow/workflow/blob/main/docs/workflow-messages-architecture.md

Implements an approval workflow that repeatedly receives messages from an 'approval_stream' stream. It waits for new messages using waitForCondition when the queue is empty, processes each approval, consumes the message, and breaks when all approvals are received.

```php
// Approval workflow that receives multiple approvals
while (true) {
    $messages = $messageService->receiveMessages($run, "approval_stream");
    
    if ($messages->isEmpty()) {
        // Wait for more messages
        yield waitForCondition(fn() => $messageService->hasUnconsumedMessages($run, "approval_stream"));
        continue;
    }
    
    foreach ($messages as $message) {
        $approval = json_decode($message->payload_reference, true);
        processApproval($approval);
        $messageService->consumeMessage($run, $message, $historySequence++);
    }
    
    if (allApprovalsReceived()) {
        break;
    }
}
```

--------------------------------

### Post-deployment health check loop

Source: https://github.com/durable-workflow/workflow/blob/main/docs/deployment/multi-node-requirements.md

Post-deployment verification script that loops through nodes 1 to 5, checking health on each with curl.

```bash
# Verify all nodes responding
for node in node-{1..5}; do
  curl https://$node.example.com/api/health
done
```

--------------------------------

### Shared Database Connection Configuration

Source: https://github.com/durable-workflow/workflow/blob/main/docs/deployment/multi-node-requirements.md

Shared database credentials for all nodes in a multi-node deployment. Supports MySQL 8.0+, PostgreSQL 13+, and MariaDB 10.5+. Use identical credentials on every node.

```env
DB_CONNECTION=mysql
DB_HOST=db.internal.example.com
DB_PORT=3306
DB_DATABASE=workflows
DB_USERNAME=workflow_user
DB_PASSWORD=<secure-password>
```

--------------------------------

### All-node environment variables configuration

Source: https://github.com/durable-workflow/workflow/blob/main/docs/deployment/multi-node-requirements.md

Lists the primary environment variables that must be identical across all nodes, including namespace, compatibility builds, task dispatch mode, and limit values. The legacy WORKFLOW_V2_* names are honored as fallbacks during the deprecation window, but new deployments should use these DW_V2_* primary names.

```env
# Namespace (consistent across nodes)
DW_V2_NAMESPACE=production

# Compatibility (deploy same build to all nodes)
DW_V2_CURRENT_COMPATIBILITY=build-20260415-1a2b3c4
DW_V2_SUPPORTED_COMPATIBILITIES=build-20260415-1a2b3c4

# Task dispatch
DW_V2_TASK_DISPATCH_MODE=queue

# Limits (consistent across nodes)
DW_V2_LIMIT_PENDING_ACTIVITIES=2000
DW_V2_LIMIT_PENDING_CHILDREN=1000
# ... etc
```

--------------------------------

### Check for clock skew between nodes

Source: https://github.com/durable-workflow/workflow/blob/main/docs/deployment/multi-node-requirements.md

Run this command on all nodes to compare their UTC clocks. Clock skew between nodes can cause duplicate task execution.

```bash
date -u # Run on all nodes, compare
```

--------------------------------

### Configuration helper for long poll validation

Source: https://github.com/durable-workflow/workflow/blob/main/docs/cross-node-long-poll-coordination.md

Configuration array enabling multi-node validation and mode via environment variables, with defaults for validation enabled and multi-node disabled.

```php
'v2' => [
    'long_poll' => [
        'validate_multi_node' => env('WORKFLOW_V2_VALIDATE_MULTI_NODE_CACHE', true),
        'multi_node' => env('WORKFLOW_V2_MULTI_NODE', false),
    ],
],
```

--------------------------------

### Parent-to-Child Signaling with MessageChannel::ChildSignal

Source: https://github.com/durable-workflow/workflow/blob/main/docs/workflow-messages-architecture.md

Shows a parent workflow sending a signal to a child instance using MessageChannel::ChildSignal and a stream key based on the child instance ID. The child workflow receives and processes those signals, consuming each one with the history sequence.

```php
// Parent sends signal to child
$messageService->sendMessage(
    $parentRun,
    MessageChannel::ChildSignal,
    $childInstanceId,
    $signalPayloadRef,
    "child_signals:{$childInstanceId}",
);

// Child receives signals
$signals = $messageService->receiveMessages($childRun, "child_signals:{$childInstanceId}");
foreach ($signals as $signal) {
    handleSignal($signal);
    $messageService->consumeMessage($childRun, $signal, $historySequence);
}
```

--------------------------------

### Query Methods

Source: https://github.com/durable-workflow/workflow/blob/main/docs/architecture/workflow-child-calls-architecture.md

Query helpers for child call tracking and lineage.

```APIDOC
## getOpenChildren

### Description
Retrieves all open children for a parent run.

### Method
getOpenChildren

### Signature
```php
public function getOpenChildren(WorkflowRun $parentRun): Collection
```

### Parameters
- `$parentRun` (WorkflowRun) - Required - The parent workflow run

### Returns
- Collection - Collection of open child calls

---

## getAllChildren

### Description
Retrieves all children for a parent run.

### Method
getAllChildren

### Signature
```php
public function getAllChildren(WorkflowRun $parentRun): Collection
```

### Parameters
- `$parentRun` (WorkflowRun) - Required - The parent workflow run

### Returns
- Collection - Collection of all child calls

---

## getChildBySequence

### Description
Retrieves a child call by its history event sequence.

### Method
getChildBySequence

### Signature
```php
public function getChildBySequence(WorkflowRun $parentRun, int $sequence): ?WorkflowChildCall
```

### Parameters
- `$parentRun` (WorkflowRun) - Required - The parent workflow run
- `$sequence` (int) - Required - The history event sequence

### Returns
- ?WorkflowChildCall - The child call or null if not found

---

## countOpenChildren

### Description
Counts open children for a parent run.

### Method
countOpenChildren

### Signature
```php
public function countOpenChildren(WorkflowRun $parentRun): int
```

### Parameters
- `$parentRun` (WorkflowRun) - Required - The parent workflow run

### Returns
- int - Number of open children

---

## hasOpenChildren

### Description
Checks if a parent run has any open children.

### Method
hasOpenChildren

### Signature
```php
public function hasOpenChildren(WorkflowRun $parentRun): bool
```

### Parameters
- `$parentRun` (WorkflowRun) - Required - The parent workflow run

### Returns
- bool - True if there are open children, false otherwise

---

## getChildrenByInstanceId

### Description
Retrieves children by their child instance ID.

### Method
getChildrenByInstanceId

### Signature
```php
public function getChildrenByInstanceId(string $childInstanceId): Collection
```

### Parameters
- `$childInstanceId` (string) - Required - The child instance ID

### Returns
- Collection - Collection of child calls with the given instance ID
```

--------------------------------

### Node-specific environment variables for unique worker configuration

Source: https://github.com/durable-workflow/workflow/blob/main/docs/deployment/multi-node-requirements.md

Shows the node-specific environment variables that can have unique values per node, covering worker identity, local storage, and logging settings.

```env
# Worker identity (unique per node)
APP_NAME=workflow-node-1

# Local storage
FILESYSTEM_DISK=local

# Logging
LOG_CHANNEL=stack
LOG_LEVEL=info
```

--------------------------------

### Run migrations on leader node only

Source: https://github.com/durable-workflow/workflow/blob/main/docs/deployment/multi-node-requirements.md

Command to run database migrations on the deployment leader node only before deploying to other nodes. Other nodes will see the migrated schema on boot; do not run migrations on multiple nodes simultaneously.

```bash
# On deployment leader node
php artisan migrate --force
```

--------------------------------

### Child Call Query Methods

Source: https://github.com/durable-workflow/workflow/blob/main/docs/architecture/workflow-child-calls-architecture.md

Query helpers for child call tracking and lineage.

```php
public function getOpenChildren(WorkflowRun $parentRun): Collection
public function getAllChildren(WorkflowRun $parentRun): Collection
public function getChildBySequence(WorkflowRun $parentRun, int $sequence): ?WorkflowChildCall
public function countOpenChildren(WorkflowRun $parentRun): int
public function hasOpenChildren(WorkflowRun $parentRun): bool
public function getChildrenByInstanceId(string $childInstanceId): Collection
```

--------------------------------

### External System Integration with MessageChannel::External

Source: https://github.com/durable-workflow/workflow/blob/main/docs/workflow-messages-architecture.md

Demonstrates an external webhook delivering a message through an internal system workflow using MessageChannel::External, with correlation and idempotency IDs. The workflow then processes webhooks from a stream key like 'webhooks:payment_confirmed', handling each and consuming it.

```php
// External webhook delivers message
$messageService->sendMessage(
    $systemRun, // Internal system workflow
    MessageChannel::External,
    $workflowInstanceId,
    $webhookPayloadRef,
    "webhooks:{$webhookType}",
    $webhookId, // correlation
    $webhookId, // idempotency
);

// Workflow processes webhooks
$webhooks = $messageService->receiveMessages($run, "webhooks:payment_confirmed");
foreach ($webhooks as $webhook) {
    handleWebhook($webhook);
    $messageService->consumeMessage($run, $webhook, $historySequence);
}
```

--------------------------------

### Define a query method with #[QueryMethod]

Source: https://github.com/durable-workflow/workflow/wiki/4.-Features

Use the QueryMethod annotation to define a method that returns workflow state without affecting execution. The method can return data from the workflow.

```php
use Workflow\QueryMethod;
use Workflow\Workflow;

class MyWorkflow extends Workflow
{
    private bool $ready = false;

    #[QueryMethod]
    public function getReady(): bool
    {
        return $this->ready;
    }
}
```

--------------------------------

### LongPollWakeStore Interface Definition

Source: https://github.com/durable-workflow/workflow/blob/main/docs/long-poll-coordination.md

Defines the required operations for the wake store contract: snapshot, changed, and signal. Used to capture version stamps, detect changes, and increment versions.

```php
interface LongPollWakeStore
{
    // Capture current version stamps for channels
    public function snapshot(array $channels): array;
    
    // Check if any channel versions changed since snapshot
    public function changed(array $snapshot): bool;
    
    // Increment version stamps for channels
    public function signal(string ...$channels): void;
}
```

--------------------------------

### Run ECS and PHPStan quality checks

Source: https://github.com/durable-workflow/workflow/blob/main/CONTRIBUTING.md

Run quality checks before opening a pull request. ECS has a check-only command for review and a Composer command that applies fixes. composer lint runs the same PHPStan analysis with verbose output.

```bash
vendor/bin/ecs check
composer ecs
composer stan
```

--------------------------------

### Possible status() return values

Source: https://github.com/durable-workflow/workflow/wiki/3.-Defining-Workflows-and-Activities

The status() method returns one of these string constants representing the workflow state.

```text
WorkflowCreatedStatus
WorkflowCompletedStatus
WorkflowFailedStatus
WorkflowPendingStatus
WorkflowRunningStatus
WorkflowWaitingStatus
```

--------------------------------

### Trigger a signal on a workflow instance

Source: https://github.com/durable-workflow/workflow/wiki/4.-Features

Call the signal method on the workflow instance to trigger it. Optional arguments can be passed to the signal method.

```php
use Workflow\WorkflowStub;

$workflow = WorkflowStub::make(MyWorkflow::class);

$workflow->setReady(true);
```
Tokens:
Raw