Temporal PHP SDK samples

The samples in this repository demonstrate the various capabilities of the Temporal PHP SDK used in conjunction with the Temporal Server.

If you want to learn more about the Temporal Server and how it works, read the documentation at https://docs.temporal.io.

About this README

This README provides two different approaches to setup the examples. First is relying on running PHP application in docker engine and does not require any extra work to start examples. The second approach will require to have PHP installed with GRPC extension but makes possible to start the application on host machine.

Docker Compose setup

1. Download the repository.

$ git clone [email protected]:temporalio/samples-php.git
$ cd samples-php

2. Build docker images.

$ docker compose build

3. Start server and application containers.

$ docker compose up

4. Run a sample

To run a sample in docker use:

$ docker compose exec app php app.php {sample-name}

To observe active workers:

$ docker compose exec app rr workers -i

To run feature tests in docker use:

$ docker compose exec app composer test:feat

Local Setup

1. Make sure you have PHP 8.1, or higher, installed.

2. Clone this repo and change directory into the root of the project.

$ git clone https://github.com/temporalio/samples-php
$ cd samples-php

3. Install the gRPC PHP extension

The PHP gRPC engine extension must be installed and activated in order to communicate with the Temporal Server.

Follow the instructions here: https://cloud.google.com/php/grpc

Note: For Windows machines, you can download the php_grpc.dll from the PECL website

Make sure you follow the all the steps to activate the gRPC extension in your php.ini file and install the protobuf runtime library in your project.

4. Install additional PHP dependencies

$ cd app
$ composer install

5. Download RoadRunner application server

The Temporal PHP SDK requires the RoadRunner v2023.2 application server and supervisor to run Activities and Workflows in a scalable way.

$ cd app
$ ./vendor/bin/rr get

Note: You can install RoadRunner manually by downloading its binary from the release page.

6. Run the Temporal Server

The Temporal Server must be up and running for the samples to work. The fastest way to do that is by following the Quick install guide.

You can also run the included docker-compose.yml file. Make sure to comment app section.

7. Start the application using RoadRunner

By default, all samples run using a single RoadRunner Server instance. To start the application using RoadRunner:

$ cd app
$ ./rr serve

You can now interact with the samples.

Note: You can alter number of PHP Workers in app/.rr.yaml.

8. Run a sample

Samples

Each sample has specific requirements. Follow the instructions in the README of the sample you wish to run.

Beginner samples

The following samples demonstrate much of the basic functionality and capabilities of the SDK.

• SimpleActivity: Single Activity Workflow

• ActivityRetry: How to retry an Activity

• AsyncActivity: How to call Activities asynchronously and wait for them using Promises

• AsyncActivityCompletion: An asynchronous Activity implementation

• AsyncClosure: How to run part of a Workflow asynchronously as a separate Task (coroutine)

• CancellationScope: How to explicitly cancel parts of a Workflow

• Child: Example of a child Workflow

• Cron: A Workflow that is executed according to a cron schedule

• Periodic: A Workflow that executes some logic periodically

• Exception: Example of exception propagation and wrapping

• PolymorphicActivity: Activities that extend a common interface

• Query: Demonstrates how to Query the state of a single Workflow

• Signal: Example of sending and handling a Signal

• Update: Example of Workflow Update feature

• Saga: Example of SAGA pattern support

• SearchAttributes: Example of Custom search attributes that can be used to find Workflows using predicates

Advanced samples

The following samples demonstrate some of the more complex aspects associated with running Workflows with the SDK.

• FileProcessing: Demonstrates Task routing features.

• Booking SAGA: Demonstrates Temporal approach to a trip booking SAGA.

• Money Transfer: Basic money transfer example.

• MoneyBatch: Demonstrates a situation when a single deposit should be initiated for multiple withdrawals.

• Updatable Timer: Demonstrates the use of a helper class which relies on Workflow.await to implement a blocking sleep that can be updated at any moment.

• Subscription: Demonstrates a long-running process associated with a user ID. The process charges the user once every 30 days after a one month free trial period.

• Interceptors: Demonstrates how to use Workflow and Activity interceptors to implement custom logic.

Testing samples

• Feature: Demonstrates how to mock activities and test Workflows using temporal test server.