temporalio / samples-php

Temporal PHP SDK samples

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

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.

samples-php's Issues

Allow users to switch between cloud and localhost when running samples

Allow users to run samples against the cloud if an environment variable is set. Otherwise, default to localhost. See: temporalio/features#454

PHP Docker usage examples

when you run any example using the configuration docker

E0201 16:23:53.596260122     170 thread_pool.cc:253]                   Waiting for thread pool to idle before forking
E0201 16:23:56.596381093     170 thread_pool.cc:253]                   Waiting for thread pool to idle before forking
E0201 16:23:59.596502744     170 thread_pool.cc:253]                   Waiting for thread pool to idle before forking

[Feature Request] mTLS connection sample

Show how to connect to Temporal with mTLS setup for both client and worker.

We'll embed code snippets from the sample in the documentation repo.

[Feature Request] Upgrade to php 8.1 or 8.2

Is your feature request related to a problem? Please describe.

I tried to install docker with PHP 8.1, but warnings are issued from the PHP side. And because of this, the app container falls.

Describe the solution you'd like

Additional context

CronSchedule cannot be used because WorkflowStartDelay is always sent to server

What are you really trying to do?

I'm trying to start a workflow execution with CronSchedule set with SDK 2.7.2

Describe the bug

When CronSchedule is configured for a workflow, the server rejects the start request with error "CronSchedule and WorkflowStartDelay may not be used together"

Minimal Reproduction

Execute the Cron sample in php-samples, no need for any modification.

Environment/Versions

• OS and processor: Linux
• Temporal Version: 1.21.5
• Are you using Docker or Kubernetes or building Temporal from source? Kubernetes

Additional context

What I think is happening:

In Go SDK they check if WorkflowStartDelay is not zero and only send it if it is not. PHP SDK sends it on every request, so when CronSchedule is set as well, the server rejects the request.

[Feature Request] mTLS sample that shows how to connect to a Temporal Cloud namespace

The existing mTLS sample works well for local development, but some fields need to be changed to connect to Temporal Cloud. Would make it a lot easier if a sample showed this in more detail.

Docker image error

when you run any example using the configuration docker:

Docker image:

FROM php:8.1.15-cli

RUN apt-get update && apt-get install -y --no-install-recommends \
  nano \
  bash \
  libzip-dev \
  unzip \
  libonig-dev

# Install PHP Extensions
ENV CFLAGS="$CFLAGS -D_GNU_SOURCE"
RUN docker-php-ext-install zip \
  && docker-php-ext-install opcache sockets mbstring \
  && docker-php-ext-enable opcache sockets mbstring

# Protobuf and GRPC
ENV PROTOBUF_VERSION "3.19.2"
RUN pecl channel-update pecl.php.net
RUN pecl install protobuf-${PROTOBUF_VERSION} grpc \
    && docker-php-ext-enable protobuf grpc

# Install Temporal CLI
COPY --from=temporalio/admin-tools /usr/local/bin/tctl /usr/local/bin/tctl

# Install Composer
COPY --from=composer /usr/bin/composer /usr/local/bin/composer

# Wait for Temporal service to star up
COPY wait-for-temporal.sh /usr/local/bin
RUN chmod +x /usr/local/bin/wait-for-temporal.sh

# Copy application codebase
WORKDIR /var/app
COPY app/ /var/app

RUN composer install

# Setup RoadRunner
RUN vendor/bin/rr get --no-interaction \
    && mv rr /usr/local/bin/rr \
    && chmod +x /usr/local/bin/rr

Error:

Deprecated: Return type of Google\Protobuf\Internal\MapField::offsetGet($index) should either be compatible with ArrayAccess::offsetGet(mixed $offset): mixed, or the #[\ReturnTypeWillChange] attribute should be used to temporarily suppress the notice in Unknown on line 0
Deprecated: Return type of Google\Protobuf\Internal\MapField::offsetSet($index, $newval) should either be compatible with ArrayAccess::offsetSet(mixed $offset, mixed $value): void, or the #[\ReturnTypeWillChange] attribute should be used to temporarily suppress the notice in Unknown on line 0
Deprecated: Return type of Google\Protobuf\Internal\MapField::offsetUnset($index) should either be compatible with ArrayAccess::offsetUnset(mixed $offset): void, or the #[\ReturnTypeWillChange] attribute should be used to temporarily suppress the notice in Unknown on line 0
Deprecated: Return type of Google\Protobuf\Internal\MapField::getIterator() should either be compatible with IteratorAggregate::getIterator(): Traversable, or the #[\ReturnTypeWillChange] attribute should be used to temporarily suppress the notice in Unknown on line 0
Deprecated: Return type of Google\Protobuf\Internal\MapField::count() should either be compatible with Countable::count(): int, or the #[\ReturnTypeWillChange] attribute should be used to temporarily suppress the notice in Unknown on line 0
Deprecated: Return type of Google\Protobuf\Internal\MapFieldIter::current() should either be compatible with Iterator::current(): mixed, or the #[\ReturnTypeWillChange] attribute should be used to temporarily suppress the notice in Unknown on line 0
Deprecated: Return type of Google\Protobuf\Internal\MapFieldIter::next() should either be compatible with Iterator::next(): void, or the #[\ReturnTypeWillChange] attribute should be used to temporarily suppress the notice in Unknown on line 0
Deprecated: Return type of Google\Protobuf\Internal\MapFieldIter::key() should either be compatible with Iterator::key(): mixed, or the #[\ReturnTypeWillChange] attribute should be used to temporarily suppress the notice in Unknown on line 0
Deprecated: Return type of Google\Protobuf\Internal\MapFieldIter::valid() should either be compatible with Iterator::valid(): bool, or the #[\ReturnTypeWillChange] attribute should be used to temporarily suppress the notice in Unknown on line 0
Deprecated: Return type of Google\Protobuf\Internal\MapFieldIter::rewind() should either be compatible with Iterator::rewind(): void, or the #[\ReturnTypeWillChange] attribute should be used to temporarily suppress the notice in Unknown on line 0
��
B�]f{"pid":28}

Could anyone help me?

[Feature Request] Update dependencies in docker-compose.yml

Recommended updates:

• Temporal to 1.20.0 (currently 1.16.2)
• Temporal UI to 2.10.3 (currently 1.13.0)

Samples for Schedules

[Bug] Wrong prefix in the samples

What are you really trying to do?

Describe the bug

The current samples need to have their own prefix, which is basically the last part of the Namespace of the Activity. At least in this setup.

However, if you do not know, that the LocalActivity-Interfaces uses SimpleActivity as a prefix, any change made to the class Temporal\Samples\SimpleActivity\GreetingActivity will not be respected.

<?php

/**
 * This file is part of Temporal package.
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

declare(strict_types=1);

namespace Temporal\Samples\LocalActivity;

use Temporal\Activity\LocalActivityInterface;
use Temporal\Activity\ActivityMethod;

#[LocalActivityInterface(prefix: 'SimpleActivity.')]
interface GreetingActivityInterface
{
    #[ActivityMethod(name: "ComposeGreeting")]
    public function composeGreeting(
        string $greeting,
        string $name
    ): string;
}

Minimal Reproduction

1. Change any code in the method Temporal\Samples\SimpleActivity\GreetingActivity::composeGreeting().
2. Ensure that you edited the method in the namespace SimpleActivity!
3. Reset the worker ./rr reset
4. Run php app.php simple-activity
5. You will see that the output comes from Temporal\Samples\LocalActivity\GreetingActivity::composeGreeting()

<?php

/**
 * This file is part of Temporal package.
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

declare(strict_types=1);

namespace Temporal\Samples\SimpleActivity;

use Temporal\Activity;

// @@@SNIPSTART php-hello-activity
class GreetingActivity implements GreetingActivityInterface
{
    public function composeGreeting(string $greeting, string $name): string
    {
        return $greeting . ' my code changes ' . $name;
    }
}
// @@@SNIPEND

Environment/Versions

• OS and processor: Macbook Pro M1
• This docker-setup

Additional context

[Feature Request] Add DSL example

https://github.com/temporalio/samples-go/tree/main/dsl

Remove "use Workflow.getLogger" comment from SagaWorkflow example

There is a comment in SagaWorkflow example which contradicts SDK code:

In production code please always use Workflow.getLogger to log messages in workflow code.

There is no Workflow::getLogger method.

[Bug] Following the instructions does not result in a working setup

What are you really trying to do?

I want to see Temporal in action with the PHP SDK

Describe the bug

docker-compose up fails with this message:

temporal                | Waiting for Temporal server to start...
temporal                | 2022/03/11 23:08:50 Loading config; env=docker,zone=,configDir=config
temporal                | 2022/03/11 23:08:50 Loading config files=[config/docker.yaml]
temporal                | {"level":"info","ts":"2022-03-11T23:08:50.439Z","msg":"Build info","timestamp":"2022-01-10T22:38:35.000Z","git-revision":"b535b87fb","platform":"amd64","go-version":"go1.17.3","server-version":"1.14.2","logging-call-at":"main.go:135"}
temporal                | Unable to create dynamic config client. Error: unable to validate dynamic config: dynamic config: config/dynamicconfig/development.yaml: stat config/dynamicconfig/development.yaml: no such file or directory
temporal exited with code 1

Minimal Reproduction

docker-compose up

Environment/Versions

Docker version 20.10.7, build 20.10.7-0ubuntu5~20.04.2

Additional context

I only cloned the repo and ran docker-compose up

[Feature Request] Encryption and codec server sample

Describe the solution you'd like

Need to show how to write an encryption codec and a codec server for use from the UI. See Go, TypeScript, Python, and/or .NET samples repositories. Ideally the codec is compatible with all of those.

Add Roadrunner Temporal metrics with dashboard

It would be nice to add temporal metrics dashboard integrated with Roadrunner metrics plugin

Links:
https://docs.temporal.io/references/sdk-metrics
https://github.com/roadrunner-server/roadrunner/blob/8cb2c6f4c5a52a867ccfb1768a4dbcd28998f04c/.rr.yaml#L198
https://github.com/temporalio/roadrunner-temporal/blob/master/tests/configs/.rr-metrics.yaml

Add interceptors sample

Add inceptor's examples to PHP SDK.

https://github.com/temporalio/samples-java/tree/main/core/src/main/java/io/temporal/samples/retryonsignalinterceptor
https://github.com/temporalio/samples-java/tree/main/core/src/main/java/io/temporal/samples/countinterceptor