Temporal Clients

How to connect a Temporal Client to a Temporal Service

A Temporal Client enables you to communicate with the Temporal Service. Communication with a Temporal Service includes, but isn't limited to, the following:

• Starting Workflow Executions.
• Sending Signals to Workflow Executions.
• Sending Queries to Workflow Executions.
• Getting the results of a Workflow Execution.
• Providing an Activity Task Token.

caution

A Temporal Client cannot be initialized and used inside a Workflow. However, it is acceptable and common to use a Temporal Client inside an Activity to communicate with a Temporal Service.

When you are running a Temporal Service locally (such as the Temporal CLI), the number of connection options you must provide is minimal. Many SDKs default to the local host or IP address and port that Temporalite and Docker Compose serve (127.0.0.1:7233).

Create an instance of the $workflowClient class and use the create() method to connect a Temporal Client to a Temporal Service.

Specify the target host, localhost:7223, parameter as a string and provide the TLS configuration for connecting to a Temporal Service.

use Temporal\Client\GRPC\ServiceClient;
use Temporal\Client\WorkflowOptions;
# . . .
$workflowClient = Temporal\Client\WorkflowClient::create(
     ServiceClient::createSSL(
         'localhost:7233',
         'certs/ca.cert',
         'certs/client.key',
         'certs/client.pem',
         'tls-sample',
     ),
 );

To provide the client options as an environmental variable, add the tls option to the RoadRunner configuration file and pass the path to the file.

temporal:
  # . . .
  tls:
    key: 'certs/client.key'
    cert: 'certs/client.pem'
    root_ca: 'certs/ca.cert'
    client_auth_type: require_and_verify_client_cert
    server_name: 'tls-sample'

Then update your application and use the SSL connection for ServiceClient.

$workflowClient = Temporal\Client\WorkflowClient::create(
     ServiceClient::createSSL(
         'localhost:7233',
         getenv('TEMPORAL_SERVER_ROOT_CA_CERT_PATH'),
         getenv('TEMPORAL_CLIENT_KEY_PATH'),
         getenv('TEMPORAL_CLIENT_CERT_PATH'),
         getenv('TEMPORAL_SERVER_NAME_OVERRIDE')
     ),
 );

How to start a Workflow Execution

Workflow Execution semantics rely on several parameters—that is, to start a Workflow Execution you must supply a Task Queue that will be used for the Tasks (one that a Worker is polling), the Workflow Type, language-specific contextual data, and Workflow Function parameters.

In the examples below, all Workflow Executions are started using a Temporal Client. To spawn Workflow Executions from within another Workflow Execution, use either the Child Workflow or External Workflow APIs.

See the Customize Workflow Type section to see how to customize the name of the Workflow Type.

A request to spawn a Workflow Execution causes the Temporal Service to create the first Event (WorkflowExecutionStarted) in the Workflow Execution Event History. The Temporal Service then creates the first Workflow Task, resulting in the first WorkflowTaskScheduled Event.

Workflows can be started both synchronously and asynchronously. You can use typed or untyped Workflows stubs available via Temporal\Client\WorkflowClient. To create a Workflow Client:

use Temporal\Client\GRPC\ServiceClient;
use Temporal\Client\WorkflowClient;

$workflowClient = WorkflowClient::create(ServiceClient::create('localhost:7233'));

Synchronous start

A synchronous start initiates a Workflow and then waits for its completion. The started Workflow will not rely on the invocation process and will continue executing even if the waiting process crashes or stops.

Be sure to acquire the Workflow interface or class name you want to start. For example:

#[WorkflowInterface]
interface AccountTransferWorkflowInterface
{
    #[WorkflowMethod(name: "MoneyTransfer")]
    #[ReturnType('int')]
    public function transfer(
        string $fromAccountId,
        string $toAccountId,
        string $referenceId,
        int $amountCents
    );
}

To start the Workflow in sync mode:

$accountTransfer = $workflowClient->newWorkflowStub(
    AccountTransferWorkflowInterface::class
);

$result = $accountTransfer->transfer(
    'fromID',
    'toID',
    'refID',
    1000
);

Asynchronous start

An asynchronous start initiates a Workflow Execution and immediately returns to the caller without waiting for a result. This is the most common way to start Workflows in a live environment.

To start a Workflow asynchronously, pass the Workflow stub instance and start parameters into the WorkflowClient->start method.

$accountTransfer = $workflowClient->newWorkflowStub(
    AccountTransferWorkflowInterface::class
);

$run = $this->workflowClient->start($accountTransfer, 'fromID', 'toID', 'refID', 1000);

After the Workflow is started, you can receive the Workflow Id via the WorkflowRun object returned by the start method:

$run = $workflowClient->start($accountTransfer, 'fromID', 'toID', 'refID', 1000);

var_dump($run->getExecution()->getID());

Recurring start

You can start a Workflow Execution on a regular schedule with the CronSchedule option.