v2.11.0

Worker

Feature Flags

Since version 2.11.0, the SDK has introduced feature flags that allow you to change the behavior of the SDK at the level of the entire PHP worker (process).
They are introduced for a consistent migration to more correct behavior, which will be established in the next major version or earlier.

To set a feature flag, you need to use the Temporal\Worker\FeatureFlags class in the beginning of your worker script:

use Temporal\Worker\FeatureFlags;

// Include the Composer autoloader
require __DIR__ . '/vendor/autoload.php';

// Set the feature flags
FeatureFlags::$workflowDeferredHandlerStart = true;
FeatureFlags::$warnOnWorkflowUnfinishedHandlers = true;

Signal with start

An important fix was made in the SDK: previously, if a Workflow was started with a Signal, the Workflow method would begin execution first.
This happened because the initialization of the Workflow method generator would start executing the generator code up to the first yield.
However, this behavior does not meet expectations: Signals should start first, followed by the Workflow method.

Since this change may break backward compatibility, it has been hidden behind a Feature Flag Temporal\Worker\FeatureFlags::$workflowDeferredHandlerStart.

Warn about unfinished handlers

Added logging of unfinished Signal and Update handlers when a Workflow finishes.

Logging is performed using the error_log() function and by default is output to stderr.

The flag responsible for this behavior is Temporal\Worker\FeatureFlags::$warnOnWorkflowUnfinishedHandlers, which is also disabled by default.
It is recommended to enable this flag and assess its impact on your application, as this behavior is likely to be enabled by default in future SDK versions.

Additionally, if unfinished handlers are not an error, you can individually set the $unfinishedPolicy option in the corresponding attribute

#[Workflow\WorkflowInterface]
interface MyWorkflow
{
    #[Workflow\WorkflowMethod]
    public function run();

    #[Workflow\SignalMethod(unfinishedPolicy: HandlerUnfinishedPolicy::Abandon)]
    public function mySignal(): void;

    #[Workflow\UpdateMethod(unfinishedPolicy: HandlerUnfinishedPolicy::Abandon)]
    public function myUpdate(): void;
}

To determine if all handlers have finished, you can use the new method Workflow::allHandlersFinished():

#[Workflow\WorkflowMethod]
public function handler()
{
    // ...

    // Wait for all handlers to finish
    yield Workflow::await(
        static fn() => Workflow::allHandlersFinished(),
    );
}

Workflow Update

Common

Client:

• Added WorkflowUpdateRPCTimeoutOrCanceledException that will be thrown instead of TimeoutException in Update cases.
• Exposed the new WorkflowStub::getUpdateHandle() method that returns UpdateHandle by UpdateId:

  $stub = $workflowClient->newUntypedRunningWorkflowStub($wfId, $wfRunId, $wfType);
  $handle = $stub->getUpdateHandle($updateId);
  $handle->getResult(5);

Worker:

• Now ExceptionInterceptor is used to detect that exception is error that breaks task or failure that fails update.
• Using the new method Workflow::getUpdateContext(), you can get UpdateContext that contains UpdateId.

Register Update handler dynamically

Previously, only Signal and Query handlers could be registered in a Workflow dynamically. Now, this is also possible for Update handlers.
The method Workflow::registerUpdate() allows passing a validator along with the handler:

// Workflow scope

Workflow::registerUpdate(
   'my-update',
   fn(Task $task) => $this->queue->push($task),
   fn(Task $task) => $this->isValidTask($task) or throw new \InvalidArgumentException('Invalid task'),
);

Schedule Update with Search Attributes

A new way to update Schedule via callback, similar to other SDKs, has been added.
The method ScheduleHandle::update() accepts a closure that takes ScheduleUpdateInput and returns ScheduleUpdate.
ScheduleUpdateInput is generated on the SDK side along with the describe() method call.

Updating Schedule via callback allows modifying Search Attributes:

$handle->update(
    fn (ScheduleUpdateInput $input): ScheduleUpdate => ScheduleUpdate::new($input->description->schedule)
        ->withSearchAttributes(
            $input->description->searchAttributes
                ->withValue('foo', 'bar'),
                ->withValue('bar', 42),
        );
);

Other changes

• Added getter for ActivityPrototype::$factory by @Nyholm in #492
• Updated WorkerOptions by @roxblnfk in #489
• Exposed ShouldContinueAsNew and HistorySize by @roxblnfk in #475

  Workflow::getInfo()->historySize;
  Workflow::getInfo()->shouldContinueAsNew;

Pull Requests

• Divide errors and failures in updates by @roxblnfk in #473
• Update dependencies by @roxblnfk in #474
• Add acceptance tests by @roxblnfk in #482
• Expose UpdateId in interceptors and workflow scope by @roxblnfk in #477
• Expose ShouldContinueAsNew and HistorySize by @roxblnfk in #475
• Expose WorkflowStub::getUpdateHandle by @roxblnfk in #484
• Start Workflow Method after Signal if it's' signalWithStart by @roxblnfk in #483
• Expose Workflow::allHandlersFinished() by @roxblnfk in #486
• Remove final from WorkflowInterface by @Nyholm in #487
• Update WorkerOptions by @roxblnfk in #489
• Add WorkflowUpdateRPCTimeoutOrCanceledException by @roxblnfk in #490
• Warn about unfinished handlers by @roxblnfk in #488
• Remove unused and invalid use statement by @Nyholm in #493
• Add getter for ActivityPrototype::$factory by @Nyholm in #492
• Register Update handler dynamically by @roxblnfk in #500
• Schedule update with Search Attributes by @roxblnfk in #504
• Actualize CS Fixer config, update CI by @roxblnfk in #506
• Move FeatureFlags class into Worker namespace by @roxblnfk in #510
• Expose next retry delay on Application Failure by @roxblnfk in #511

New Contributors

• @Nyholm made their first contribution in #487

Full Changelog: v2.10.3...v2.11.0