v2.15.0

Warning

RoadRunner 2025.1.2 is required.

Task Queue Priority

Task Queue Priority allows you to control the execution order of workflows, activities, and child workflows based on assigned priority values within a single task queue. You can select a priority level in the integer range 1...5. A lower value implies higher priority. The default priority if unspecified is in the middle of the range, 3.

Note

As this feature is currently in Pre-release stage, it is not intended for production use at this time.
See product release stages for more information.

Pre-requisites

• If using Temporal Cloud, please contact Temporal support or your Temporal account team to enable this feature for your cloud namespace(s).
• If self-hosting Temporal, use the latest pre-release development server and set matching.useNewMatcher dynamic config on the relevant task queues (or namespaces).

Client API

# New Priority DTO
$priority = Priority::new(priorityKey: 1);

# Set Priority on a Workflow
$workflow = $workflowClient->newWorkflowStub(
    OrderWorkflowInterface::class,
    WorkflowOptions::new()
        ->withTaskQueue('task-queue')
        ->withPriority($priority),
);

Workflow API

# New Priority DTO
$priority = Priority::new(priorityKey: 1);

# Set Priority on an Activity
$activity = Workflow::newActivityStub(
    ActivityInterface::class,
    ActivityOptions::new()
        ->withTaskQueue('task-queue')
        ->withStartToCloseTimeout('5 minutes')
        ->withPriority($priority),
);

# Set Priority on a Child Workflow
$childWorkflow = Workflow::newChildWorkflowStub(
    ChildWorkflowInterface::class,
    ChildWorkflowOptions::new()
        ->withTaskQueue('task-queue')
        ->withPriority($priority),
);

Get Priority value in Workflow or Activity

// Get
$priority = Activity::getInfo()->priority;
$priority = Workflow::getInfo()->priority;

Note

• Lower numbers = higher priority.
• Tasks with the same priority are scheduled in FIFO order.
• If priority is unsupported by the server, these settings are silently ignored.
• Remember this feature is not production ready at this stage.

User Metadata

Handler Descriptions

You can now add descriptions to Query, Signal, and Update handlers. Descriptions are available through the description parameter in QueryMethod, SignalMethod, and UpdateMethod attributes, as well as in the Workflow::registerSignal(), Workflow::registerQuery(), and Workflow::registerUpdate() methods. These descriptions will be displayed in the Temporal UI for better handler documentation.

Using Attributes:

#[QueryMethod('get_counter', description: 'Get the current counter value')]
public function getCounter(): int
{
    return $this->counter;
}

#[SignalMethod('inc_counter', description: 'Increment the counter value')]
public function incCounter(): void
{
    ++$this->counter;
}

Using Registration Methods:

Workflow::registerQuery('get_counter', $this->getCounter(...), 'Get the current counter value');
Workflow::registerSignal('increment_counter', $this->incrementCounter(...), 'Increment the counter value');

Activity and Timer Summaries

You can now add custom metadata summaries to Activity and Timer executions. These summaries will be displayed in the Workflow history within the Temporal UI, providing better visibility into workflow execution details.

Activity Summary:

yield Workflow::executeActivity(
    type: 'activity_type',
    options: ActivityOptions::new()
        ->withScheduleToCloseTimeout(30)
        ->withSummary('Process user payment'),
);

Timer Summary:

yield Workflow::timer(
    interval: 30,
    options: TimerOptions::new()->withSummary('Wait for external service response'),
);

Activity Pause

When a heartbeating activity is paused, an ActivityPausedException will be thrown.
Added Activity::getCancellationDetails() that returns ActivityCancellationDetails DTO that provides the reasons for the activity's cancellation.

Pull Requests

• Null coalesce in AttributeMapper instead of try/catch by @shanginn in #615
• Fixed type WorkflowClientCallsInterceptor by @root-aza in #612
• Add versioning acceptance tests by @roxblnfk in #614
• Add Child Workflow ID test by @roxblnfk in #617
• Expose Priority by @roxblnfk in #607
• Expose metadata query support by @roxblnfk in #616
• Add PromiseInterface stub for IDE by @roxblnfk in #627
• Expose summary option for timers and activities by @roxblnfk in #626
• Testing: fixed downloading of temporal-test-server for arm64 by @root-aza in #629
• Fix prototype existence check in ArrayRepository by @roxblnfk in #631
• Process special Temporal builtin prefixes by @roxblnfk in #630
• Activity pause by @roxblnfk in #620

Full Changelog: v2.14.1...v2.15.0