Expose Workflow Updates

[roxblnfk]

What was changed

Exposed Update functionality.

Added attributes:

• UpdateMethod
• UpdateValidatorMethod

RoadRunner requirement ^2023.3.11

Note

Temporal tes-server doesn't support Updates. That's why the tests was skipped in CI

Checklist

• Part of PHP Workflow update support #323
• How was this tested:
  • added autotests
  • tested manually

TODO:

• Dynamic Update handlers
• Make sure Interceptors work
• Write tests
• Polishing
• Samples

Documentation

How to develop with Updates

An Update is an operation that can mutate the state of a Workflow Execution and return a response.

How to define Updates

An Update handler has a name, arguments, response, and an optional validator.

• The name, also called an Update type, is a string.
• The arguments and response must be serializable.

The #[UpdateMethod] attribute indicates that the method is used to handle and respond to update requests.

#[UpdateMethod]
public function myUpdate(string $signalName);

How to handle Updates in a Workflow

Workflows listen for Update by the update's name.

The handler method can accept multiple serializable input parameters, but it's recommended using only a single parameter.
The function can return a serializable value or void.

#[WorkflowInterface]
interface FileProcessingWorkflow {
    #[WorkflowMethod]
    public function processFile(Arguments $args);

    #[UpdateMethod]
    public function pauseProcessing(): void;
}

Update handlers, unlike Query handlers, can change Workflow state.

The Updates type defaults to the name of the method. To overwrite this default naming and assign a custom Update type, use the #[UpdateMethod] attribute with the name parameter.

#[WorkflowInterface]
interface FileProcessingWorkflow {
    #[WorkflowMethod]
    public function processFile(Arguments $args);

    #[UpdateMethod(name: "pause")]
    public function pauseProcessing();
}

How to validate an Update in a Workflow

Validate certain aspects of the data sent to the Workflow using an Update Validator method. For instance, a counter Workflow might never want to accept a non-positive number. Use the #[UpdateValidatorMethod] attribute and set name to the name of your Update handler. Your Update Validator should accept the same input parameters as your Update Handler and return void.

#[WorkflowInterface]
interface GreetingWorkflow {
    #[WorkflowMethod]
    public function getGreetings(): array;

    #[UpdateMethod]
    public function addGreeting(string $name): int;

    #[UpdateValidatorMethod(forUpdate: "addGreeting")]
    public function addGreetingValidator(string $name): void;
}

How to send an Update from a Client

To send an Update to a Workflow Execution from a Client, call the Update method, annotated with #[UpdateMethod] in the Workflow interface, from the Client code.

In the following Client code example, start the Workflow getGreetings and call the Update method addGreeting that is handled in the Workflow.

/** @var \Temporal\Client\WorkflowClientInterface $client */

// Create a typed Workflow stub for GreetingsWorkflow
$workflow = $client->newWorkflowStub(GreetingWorkflow::class, $workflowOptions);

// Start the Workflow
$run = $client->start($workflow);

// Send an update to the Workflow. addGreeting returns
// the number of greetings our workflow has received.
$workflow->addGreeting("World");