temporalio / temporalio/sdk-php

[Feature Request] Allow passing `AwaitOptions` to `Workflow::awaitWithTimeout()`

Open
#803 0 comments 1 reaction 1 assignee View on GitHub

@xepozz is already working on this.

Since Sep 9, 2026.

enhancement
Dominant language
PHP
Stars
421
Forks
64
Avg merge
1d 1h
Merged PRs (30d)
11

Description

Workflow::awaitWithTimeout() currently accepts a timeout interval and conditions, but does not allow passing AwaitOptions.

Internally, WorkflowContext::awaitWithTimeout() already creates an AwaitOptions instance:

$request = new NewTimer(
    new AwaitOptions($input->interval, null)
);

It would be useful to expose this option through the public API instead of always creating it with null.

One important use case is providing TimerOptions for the underlying timer, especially its summary.

For example, when multiple awaitWithTimeout() calls are running concurrently, such as inside Workflow::async(), it can be difficult to identify the corresponding timers in the Temporal UI:

$rtdsReceived = yield Workflow::awaitWithTimeout(
    CarbonInterval::seconds(30),
    fn (): bool => $this->signal->receiveRtdsResolution !== null,
);

$webSocketReceived = yield Workflow::awaitWithTimeout(
    CarbonInterval::minutes(3),
    fn (): bool => $this->signal->receiveWebSocketResolution !== null,
);

It would be useful to have an API along the lines of:

$rtdsReceived = yield Workflow::awaitWithTimeout(
    CarbonInterval::seconds(30),
    fn (): bool => $this->signal->receiveRtdsResolution !== null,
    AwaitOptions::new()->withTimerOptions(
        TimerOptions::new()->withSummary('rtds-resolution-wait'),
    ),
);

or

$rtdsReceived = yield Workflow::awaitWithTimeout(
    AwaitOptions::new()->withTimerOptions(
        CarbonInterval::seconds(30),
        TimerOptions::new()->withSummary('rtds-resolution-wait'),
    ),
    fn (): bool => $this->signal->receiveRtdsResolution !== null,
);

Or any equivalent API that allows AwaitOptions to be supplied.

The main point is that awaitWithTimeout() already uses AwaitOptions internally, so exposing AwaitOptions would allow additional await-related options to be added in the future without repeatedly changing the awaitWithTimeout() API.

In particular, this would allow the underlying timer to use TimerOptions, consistent with the existing Workflow::timer() API.

This would improve the observability of concurrent awaitWithTimeout() operations in the Temporal UI without requiring users to replace awaitWithTimeout() with custom timer logic.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.