Temporal PHP SDK

The ServiceClient provides methods to manage worker deployments, which allow for versioned deployments and controlled rollouts (ramping).

Key Operations:

• List Deployments: Use ListWorkerDeployments to see all deployments in a namespace. (Note: ListDeployments is deprecated).
• Describe Deployment: Use DescribeWorkerDeployment to get details about a specific deployment, or DescribeWorkerDeploymentVersion for a specific version.
• Set Current Version: Use SetWorkerDeploymentCurrentVersion to set the active version for a deployment series. This automatically unsets any active Ramping Version.
• Ramping/Rollouts: Use SetWorkerDeploymentRampingVersion to set a version to be rolled out gradually with a specific ramp percentage.
• Cleanup: Use DeleteWorkerDeployment to remove a deployment (must have no versions) or DeleteWorkerDeploymentVersion to manually delete a specific version.

Conditions for deleting a version:

• It is not the Current or Ramping Version.
• It has no active pollers (no task queues in that version have pollers).
• It is not draining (unless skip-drainage=true is passed).

Deprecated Methods:

• ListDeployments -> Use ListWorkerDeployments.
• GetDeploymentReachability -> Use DrainageInfo returned by DescribeWorkerDeploymentVersion.
• GetCurrentDeployment -> Use current_version returned by DescribeWorkerDeployment.
• SetCurrentDeployment -> Use SetWorkerDeploymentCurrentVersion.

The EncodedCollection class is an associative collection used to manage data that has been encoded for transport (as Payload objects) or raw values that need encoding. It acts as a bridge between your application's typed values and the Temporal Payload format.

Key behaviors:

• It can hold both raw values (to be encoded) and existing Payload objects (to be decoded).
• It requires a DataConverterInterface implementation to perform the actual encoding/decoding of values to/from Payload objects.
• It is immutable when using withValue(), returning a new instance instead of modifying the existing one.
• It implements IteratorAggregate and Countable, allowing you to loop over decoded values or check the collection size.

use Temporal\DataConverter\EncodedCollection;

// Create from raw values
$collection = EncodedCollection::fromValues(['key' => 'value'], $dataConverter);

// Add or replace a value (returns a new instance)
$newCollection = $collection->withValue('new_key', 123);

// Access a decoded value
$value = $newCollection->getValue('key');

The ClientOptions class is used to configure the behavior of a Temporal Client. It uses an immutable pattern where calling a with* method returns a new instance of ClientOptions with the updated value.

Key configuration properties include:

• namespace: The Temporal namespace to use. Defaults to 'default'.
• identity: A unique identifier for the client. By default, this is generated using the current process ID and hostname (<pid>@<hostname>).
• queryRejectionCondition: An integer value determining when queries should be rejected. This should be a valid value from the Temporal\Api\Enums\V1\QueryRejectCondition enum.

use Temporal\Client\ClientOptions;
use Temporal\Api\Enums\V1\QueryRejectCondition;

$options = (new ClientOptions())
    ->withNamespace('my-namespace')
    ->withIdentity('my-custom-identity')
    ->withQueryRejectionCondition(QueryRejectCondition::QUERY_REJECT_CONDITION_NONE);

Use LocalActivityOptions to define timeouts and retry policies for activities executed within a workflow. Local activities are managed by the workflow worker and are subject to the following configuration options:

Timeouts

• ScheduleToCloseTimeout: The end-to-end timeout for the activity. If not explicitly set, the default is the sum of scheduleToStartTimeout and startToCloseTimeout. Use withScheduleToCloseTimeout($timeout) to set this.
• StartToCloseTimeout: The maximum time allowed from the start of activity execution to its completion. Use withStartToCloseTimeout($timeout) to set this.

Retry Policy

• RetryOptions: Specifies how to retry an activity if it fails. If no RetryOptions are provided, the Temporal server provides a default policy:
  • InitialInterval: 1 second
  • BackoffCoefficient: 2.0
  • MaximumInterval: 100 x InitialInterval
  • MaximumAttempts: 0 (unlimited)

To disable retries, set MaximumAttempts to 1. Use withRetryOptions(?RetryOptions $options) to configure this.

Summary (Experimental)

• Summary: An optional single-line fixed summary for the activity that appears in the Temporal UI or CLI. Supports single-line Temporal Markdown. Use withSummary(string $summary) to set this.

use Temporal\Activity\LocalActivityOptions;
use Temporal\Common\RetryOptions;

$options = (new LocalActivityOptions())
    ->withStartToCloseTimeout(new \DateInterval('PT10S'))
    ->withRetryOptions(RetryOptions::new()->withMaximumAttempts(3));