Durable Workflow PHP SDK — API Reference

Guides

WorkflowContext
in package

FinalYes

Straight-line deterministic operations available while a workflow Fiber is replayed.

Table of Contents

Constants

MAX_PARALLEL_OPERATIONS  : mixed = 1000
MESSAGE_STREAM_CURSOR_SCHEMA  : mixed = 'durable-workflow.v2.message-stream.cursor'
MESSAGE_STREAM_SCHEMA  : mixed = 'durable-workflow.v2.message-stream.message'
MESSAGE_STREAM_SIGNAL  : mixed = '__durable_workflow_message_stream'
MAX_VERSION  : mixed = 2147483647
MIN_VERSION  : mixed = -2147483648

Properties

$runId  : string
$workflowId  : string
$allowCancellationScopeAuthoring  : bool
$allowScopedPreparedLocalActivities  : bool
$businessReplayClock  : BusinessReplayClock|null
$cancellationReplayClock  : CancellationReplayClock|null
$cancellationRequested  : bool
$cancellationScopeId  : string
$cancellationShieldDepth  : int
$captureFrames  : array<int, array<int, DeferredWorkflowOperation|ParallelWorkflowCommand>>
$codec  : PayloadCodec
$conditionWaitOccurrences  : int
$deliveredCancellationContext  : CancellationContext|null
$deliveredCancellationRequestId  : string|null
$deliveredScopeCancellations  : array<string, ScopedCancellationContext>
$deliveredScopeCleanup  : array<string, array<string, string>>
$execution  : Fiber<mixed, mixed>|null
$hasAuthoredCancellationScopes  : bool
$history  : array<string|int, mixed>
$localActivityCancellationPolicies  : array<string|int, mixed>
$localActivityExecutor  : Closure|null
$messageStreamCursors  : array<string, int>
$messageStreamMessages  : array<string, array<int, MessageStreamMessage>>
$messageStreamWaits  : array<string, int>
$prepareLocalActivities  : bool
$prepareLocalActivityGroups  : bool
$serviceOperationOrdinal  : int
$workflowCommandId  : string|null
$workflowStreamCommandOrdinal  : int

Methods

__construct()  : mixed
activity()  : mixed
all()  : array<int, mixed>
Schedule every deferred leaf, then return results in declaration order.
appendWorkflowStream()  : void
Append a replay-safe batch to a named run-scoped Workflow Stream.
cancellationContext()  : CancellationContext|ScopedCancellationContext|null
The original context becomes visible at its committed authored boundary.
cancellationShield()  : TResult
Permit deterministic cleanup without delivering the same request again.
childWorkflow()  : mixed
closeWorkflowStream()  : void
consumeMessageStreamMessages()  : array<int, MessageStreamMessage>
continueAsNew()  : never
deferActivity()  : DeferredWorkflowOperation
Prepare an activity without scheduling it until an all/parallel barrier is reached.
deferChildWorkflow()  : DeferredWorkflowOperation
Prepare a child workflow without starting it until an all/parallel barrier is reached.
deferCondition()  : DeferredWorkflowOperation
Prepare a deterministic condition or signal-derived wait for a durable group.
deferTimer()  : DeferredWorkflowOperation
Prepare a durable timer for an all/parallel barrier.
deprecatePatch()  : void
Keep a patch marker alive after the legacy branch has been removed.
errorWorkflowStream()  : void
getVersion()  : int
Select the newest supported version for a change, or replay its recorded decision.
hasPendingMessageStreamMessages()  : bool
isCancellationRequested()  : bool
localActivity()  : mixed
Execute a registered activity in this workflow worker and record its outcome durably.
messageStream()  : MessageStream
messageStreamCursor()  : int
messageStreamCursorAcknowledgements()  : array<int, array{stream_name: string, through_position: int}>
messageStreamPendingWaits()  : array<int, array{stream_name: string, after_position: int}>
parallel()  : array<int, mixed>
Alias for {@see self::all()}.
patched()  : bool
Record or replay the standard -1 (legacy) / 1 (patched) decision.
recordMessageStreamWait()  : void
replayNow()  : DateTimeImmutable
The recorded time at this invocation's consumed replay boundary.
saga()  : Saga
Create an isolated deterministic saga for activity compensation.
scheduleOrigin()  : ScheduleOrigin|null
The schedule fire that started this run, or null for a run no schedule started.
select()  : SelectionResult
Schedule every durable member and resume with the first committed winner.
serviceOperation()  : ServiceOperationResult
Call a registered service through a durable workflow command, without HTTP in workflow code.
sideEffect()  : mixed
signals()  : array<int, array<int, mixed>>
sleep()  : void
Start a durable timer and suspend until it fires.
startChildWorkflow()  : ChildWorkflowHandle
Start a child workflow and return a handle once its start is committed.
throwIfCancellationRequested()  : void
updates()  : array<int, array<int, mixed>>
upsertMemo()  : void
Merge non-indexed workflow memo metadata. Null removes a key; all other Avro values replace that key while unrelated memo entries are preserved.
upsertSearchAttributes()  : void
Explicit types bind replay to the complete type identity of non-deleted attributes. Omit the map to retain the existing value-only API.
waitCondition()  : bool
Suspend until the deterministic predicate is satisfied or its durable timeout elapses.
assertActiveFiber()  : void
assertDeferredOperation()  : DeferredWorkflowOperation|ParallelWorkflowCommand
cancellationClock()  : callable(): DateTimeImmutable
capture()  : void
captureOperation()  : DeferredWorkflowOperation|ParallelWorkflowCommand
conditionKey()  : string|null
finishWorkflowStream()  : void
isCapturing()  : bool
isScopeCleanup()  : bool
loadMessageStreamMessages()  : void
scheduleOccurrence()  : DateTimeImmutable|null
suspend()  : mixed
version()  : int|bool|null
withCancellationScope()  : WorkflowCommand

Constants

MESSAGE_STREAM_CURSOR_SCHEMA

public mixed MESSAGE_STREAM_CURSOR_SCHEMA = 'durable-workflow.v2.message-stream.cursor'

MESSAGE_STREAM_SCHEMA

public mixed MESSAGE_STREAM_SCHEMA = 'durable-workflow.v2.message-stream.message'

MESSAGE_STREAM_SIGNAL

public mixed MESSAGE_STREAM_SIGNAL = '__durable_workflow_message_stream'

Properties

$allowCancellationScopeAuthoring read-only

private bool $allowCancellationScopeAuthoring = false

$allowScopedPreparedLocalActivities read-only

private bool $allowScopedPreparedLocalActivities = false

$businessReplayClock read-only

private BusinessReplayClock|null $businessReplayClock = null

$cancellationReplayClock

private CancellationReplayClock|null $cancellationReplayClock = null

$cancellationRequested read-only

private bool $cancellationRequested = false

$deliveredCancellationRequestId

private string|null $deliveredCancellationRequestId = null

$deliveredScopeCleanup

private array<string, array<string, string>> $deliveredScopeCleanup = []

Original delivery snapshots, never renewed budgets.

$hasAuthoredCancellationScopes

private bool $hasAuthoredCancellationScopes = false

$localActivityCancellationPolicies read-only

private array<string|int, mixed> $localActivityCancellationPolicies = []

$localActivityExecutor read-only

private Closure|null $localActivityExecutor = null

$messageStreamCursors

private array<string, int> $messageStreamCursors = []

$prepareLocalActivities read-only

private bool $prepareLocalActivities = false

$prepareLocalActivityGroups read-only

private bool $prepareLocalActivityGroups = false

$workflowCommandId read-only

private string|null $workflowCommandId = null

$workflowStreamCommandOrdinal

private int $workflowStreamCommandOrdinal = 0

Methods

__construct()

public __construct(string $workflowId, string $runId, array<int, array<string, mixed>> $history, PayloadCodec $codec[, bool $cancellationRequested = false ][, Fiber<mixed, mixed>|null $execution = null ][, string|null $workflowCommandId = null ][, Closure|null $localActivityExecutor = null ][, bool $prepareLocalActivities = false ][, bool $prepareLocalActivityGroups = false ][, array<int, string> $localActivityCancellationPolicies = [] ][, bool $allowCancellationScopeAuthoring = false ][, bool $hasAuthoredCancellationScopes = false ][, bool $allowScopedPreparedLocalActivities = false ][, BusinessReplayClock|null $businessReplayClock = null ]) : mixed
Parameters
$workflowId : string
$runId : string
$history : array<int, array<string, mixed>>
$codec : PayloadCodec
$cancellationRequested : bool = false
$execution : Fiber<mixed, mixed>|null = null
$workflowCommandId : string|null = null
$localActivityExecutor : Closure|null = null
$prepareLocalActivities : bool = false
$prepareLocalActivityGroups : bool = false
$localActivityCancellationPolicies : array<int, string> = []
$allowCancellationScopeAuthoring : bool = false
$hasAuthoredCancellationScopes : bool = false
$allowScopedPreparedLocalActivities : bool = false
$businessReplayClock : BusinessReplayClock|null = null

activity()

public activity(string $activityType[, array<int, mixed> $arguments = [] ][, array<string, mixed> $options = [] ]) : mixed
Parameters
$activityType : string
$arguments : array<int, mixed> = []
$options : array<string, mixed> = []

all()

Schedule every deferred leaf, then return results in declaration order.

public all(iterable<int, callable(): mixed|DeferredWorkflowOperation> $operations) : array<int, mixed>

Closures are captured without suspending, so ordinary activity(), childWorkflow(), and sleep() calls remain straight-line. Nested all()/parallel() calls preserve their result shape. The first durable failure is thrown at this barrier.

Parameters
$operations : iterable<int, callable(): mixed|DeferredWorkflowOperation>
Return values
array<int, mixed>

appendWorkflowStream()

Append a replay-safe batch to a named run-scoped Workflow Stream.

public appendWorkflowStream(string $streamName, array<int, WorkflowStreamAppendItem> $items[, int|null $maxPendingItems = null ]) : void
Parameters
$streamName : string
$items : array<int, WorkflowStreamAppendItem>
$maxPendingItems : int|null = null

cancellationShield()

Permit deterministic cleanup without delivering the same request again.

public cancellationShield(callable(): TResult $cleanup) : TResult

Server still owns the original cleanup deadline and task lease.

Parameters
$cleanup : callable(): TResult
Tags
template
Return values
TResult

childWorkflow()

public childWorkflow(string $workflowType[, array<int, mixed> $arguments = [] ][, array<string, mixed> $options = [] ]) : mixed
Parameters
$workflowType : string
$arguments : array<int, mixed> = []
$options : array<string, mixed> = []

closeWorkflowStream()

public closeWorkflowStream(string $streamName[, int|null $retentionSeconds = null ]) : void
Parameters
$streamName : string
$retentionSeconds : int|null = null

continueAsNew()

public continueAsNew([array<int, mixed> $arguments = [] ][, string|null $workflowType = null ][, string|null $taskQueue = null ]) : never
Parameters
$arguments : array<int, mixed> = []
$workflowType : string|null = null
$taskQueue : string|null = null
Return values
never

deferActivity()

Prepare an activity without scheduling it until an all/parallel barrier is reached.

public deferActivity(string $activityType[, array<int, mixed> $arguments = [] ][, array<string, mixed> $options = [] ]) : DeferredWorkflowOperation
Parameters
$activityType : string
$arguments : array<int, mixed> = []
$options : array<string, mixed> = []
Return values
DeferredWorkflowOperation

deferChildWorkflow()

Prepare a child workflow without starting it until an all/parallel barrier is reached.

public deferChildWorkflow(string $workflowType[, array<int, mixed> $arguments = [] ][, array<string, mixed> $options = [] ]) : DeferredWorkflowOperation
Parameters
$workflowType : string
$arguments : array<int, mixed> = []
$options : array<string, mixed> = []
Return values
DeferredWorkflowOperation

deferCondition()

Prepare a deterministic condition or signal-derived wait for a durable group.

public deferCondition(callable $predicate[, string|null $key = null ][, int|float|string|DateInterval|null $timeout = null ]) : DeferredWorkflowOperation
Parameters
$predicate : callable
$key : string|null = null
$timeout : int|float|string|DateInterval|null = null
Tags
throws
InvalidArgumentException

when a string or interval timeout is unparseable or negative

Return values
DeferredWorkflowOperation

deferTimer()

Prepare a durable timer for an all/parallel barrier.

public deferTimer(int|float|string|DateInterval $seconds) : DeferredWorkflowOperation

Accepts the same int, float, string and interval durations as sleep().

Parameters
$seconds : int|float|string|DateInterval
Tags
throws
InvalidArgumentException

when a string or interval is unparseable or negative

Return values
DeferredWorkflowOperation

deprecatePatch()

Keep a patch marker alive after the legacy branch has been removed.

public deprecatePatch(string $changeId) : void
Parameters
$changeId : string

errorWorkflowStream()

public errorWorkflowStream(string $streamName, string $errorReason[, int|null $retentionSeconds = null ]) : void
Parameters
$streamName : string
$errorReason : string
$retentionSeconds : int|null = null

getVersion()

Select the newest supported version for a change, or replay its recorded decision.

public getVersion(string $changeId, int $minSupported, int $maxSupported) : int
Parameters
$changeId : string
$minSupported : int
$maxSupported : int
Return values
int

hasPendingMessageStreamMessages()

public hasPendingMessageStreamMessages(string $name) : bool
Parameters
$name : string
Return values
bool

isCancellationRequested()

public isCancellationRequested() : bool
Return values
bool

localActivity()

Execute a registered activity in this workflow worker and record its outcome durably.

public localActivity(string $activityType[, array<int, mixed> $arguments = [] ][, array<string, mixed> $options = [] ]) : mixed
Parameters
$activityType : string
$arguments : array<int, mixed> = []
$options : array<string, mixed> = []

messageStreamCursor()

public messageStreamCursor(string $name) : int
Parameters
$name : string
Return values
int

messageStreamCursorAcknowledgements()

public messageStreamCursorAcknowledgements() : array<int, array{stream_name: string, through_position: int}>
Return values
array<int, array{stream_name: string, through_position: int}>

messageStreamPendingWaits()

public messageStreamPendingWaits() : array<int, array{stream_name: string, after_position: int}>
Return values
array<int, array{stream_name: string, after_position: int}>

patched()

Record or replay the standard -1 (legacy) / 1 (patched) decision.

public patched(string $changeId) : bool
Parameters
$changeId : string
Return values
bool

recordMessageStreamWait()

public recordMessageStreamWait(string $name, int $afterPosition) : void
Parameters
$name : string
$afterPosition : int

replayNow()

The recorded time at this invocation's consumed replay boundary.

public replayNow() : DateTimeImmutable
Return values
DateTimeImmutable

scheduleOrigin()

The schedule fire that started this run, or null for a run no schedule started.

public scheduleOrigin() : ScheduleOrigin|null

It comes from recorded history, so it is identical on every replay.

Return values
ScheduleOrigin|null

serviceOperation()

Call a registered service through a durable workflow command, without HTTP in workflow code.

public serviceOperation(string $endpointName, string $serviceName, string $operationName[, mixed $request = null ][, array<string, mixed>|ServiceOperationOptions $options = [] ]) : ServiceOperationResult

The default waits for completion. Set wait_for=accepted to receive the original acceptance.

Parameters
$endpointName : string
$serviceName : string
$operationName : string
$request : mixed = null
$options : array<string, mixed>|ServiceOperationOptions = []
Return values
ServiceOperationResult

sideEffect()

public sideEffect(callable(): mixed $operation) : mixed
Parameters
$operation : callable(): mixed

signals()

public signals(string $signalName) : array<int, array<int, mixed>>
Parameters
$signalName : string
Return values
array<int, array<int, mixed>>

sleep()

Start a durable timer and suspend until it fires.

public sleep(int|float|string|DateInterval $seconds) : void

Accepts int or float seconds, a duration string such as "30 minutes" or "1h 30m", or a DateInterval or CarbonInterval. Every form rounds up to whole seconds once, so equivalent values record identical history.

Parameters
$seconds : int|float|string|DateInterval
Tags
throws
InvalidArgumentException

when a string or interval is unparseable or negative

startChildWorkflow()

Start a child workflow and return a handle once its start is committed.

public startChildWorkflow(string $workflowType[, array<int, mixed> $arguments = [] ][, array<string, mixed> $options = [] ]) : ChildWorkflowHandle

The current turn ends after the start command. The runtime commits ChildWorkflowScheduled and ChildRunStarted and gives the parent a fresh turn, so the handle's identity comes from canonical history while the child keeps running. Call await() on the handle for the child's result. Requires a runtime that advertises child_workflow_start_turn; the worker refuses the start before submitting it otherwise. Not available inside all()/parallel() groups.

Parameters
$workflowType : string
$arguments : array<int, mixed> = []
$options : array<string, mixed> = []

the same options as childWorkflow()

Return values
ChildWorkflowHandle

throwIfCancellationRequested()

public throwIfCancellationRequested() : void

updates()

public updates(string $updateName) : array<int, array<int, mixed>>
Parameters
$updateName : string
Return values
array<int, array<int, mixed>>

upsertMemo()

Merge non-indexed workflow memo metadata. Null removes a key; all other Avro values replace that key while unrelated memo entries are preserved.

public upsertMemo(array<string, mixed> $entries) : void
Parameters
$entries : array<string, mixed>

upsertSearchAttributes()

Explicit types bind replay to the complete type identity of non-deleted attributes. Omit the map to retain the existing value-only API.

public upsertSearchAttributes(array<string, mixed> $attributes[, array<string, string>|null $attributeTypes = null ]) : void
Parameters
$attributes : array<string, mixed>
$attributeTypes : array<string, string>|null = null

waitCondition()

Suspend until the deterministic predicate is satisfied or its durable timeout elapses.

public waitCondition(callable(): bool $predicate[, string|null $key = null ][, int|float|string|DateInterval|null $timeout = null ]) : bool

The result is true only when the condition was satisfied and false only when it timed out. Give repeated or otherwise ambiguous waits a stable key so replay can identify them. The timeout accepts int or float seconds, a duration string such as "30 minutes", or a DateInterval or CarbonInterval, and rounds up to whole seconds.

Parameters
$predicate : callable(): bool
$key : string|null = null
$timeout : int|float|string|DateInterval|null = null
Tags
throws
InvalidArgumentException

when a string or interval timeout is unparseable or negative

Return values
bool

cancellationClock()

private cancellationClock() : callable(): DateTimeImmutable
Return values
callable(): DateTimeImmutable

conditionKey()

private static conditionKey(string|null $key) : string|null
Parameters
$key : string|null
Return values
string|null

finishWorkflowStream()

private finishWorkflowStream(string $streamName, string|null $errorReason, int|null $retentionSeconds) : void
Parameters
$streamName : string
$errorReason : string|null
$retentionSeconds : int|null

scheduleOccurrence()

private static scheduleOccurrence(string $value) : DateTimeImmutable|null
Parameters
$value : string
Return values
DateTimeImmutable|null

version()

private version(string $changeId, int $minSupported, int $maxSupported, string $resultKind) : int|bool|null
Parameters
$changeId : string
$minSupported : int
$maxSupported : int
$resultKind : string
Return values
int|bool|null
On this page

Search results