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 git@github.com: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

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.