Skip to main content

Quickstart - Setup

Configure your local development environment to get started developing with Temporal.

Install PHP​

Make sure you have PHP installed.

If you don't have PHP: Visit the official website to download and install it.

GRPC extension​

GRPC extension is required to work with RoadRunner application server.

If you don't have ext-grpc installed: Visit the official website to download and install it.

GRPC Installation Tip

On macOS with Apple Silicon (M1/M2/M3/M4) and PHP 8.3, pecl install grpc may appear to hang or install indefinitely. If this happens, try installing a specific version:

pecl install channel://pecl.php.net/grpc-1.78.0RC2

Note: You can find the latest versions at pecl.php.net/package/grpc.

php -v

Create a Project​

Now that you have PHP installed, create a project to manage your dependencies and build your Temporal application.

mkdir temporal-hello-world
cd temporal-hello-world
composer init --name="myproject/quickstart" -n

Add Temporal PHP SDK and Configure Autoloading​

Install the Temporal SDK, then add PSR-4 autoloading to your composer.json so PHP can find your Workflow and Activity classes.

Your final composer.json should look like this. After updating, run composer dump-autoload to regenerate the autoloader.

composer require temporal/sdk
{
  "name": "myproject/quickstart",
  "require": {
      "temporal/sdk": "^2.16"
  },
  "autoload": {
      "psr-4": {
          "App\\": "src/"
      }
  }
}
composer dump-autoload

Install RoadRunner application server​

Install RoadRunner application server. It starts and manages your PHP processes that run Temporal Workers, and connects them to the Temporal Service over gRPC.

See RoadRunner installation instructions to learn about other installation methods.

Download RoadRunner with the following command:

./vendor/bin/rr get

When prompted "Do you want create default '.rr.yaml' configuration file?", answer yes. You'll replace it with the proper config in the next step.

Create a simple configuration file named .rr.yaml with the following content:

version: "3"

rpc:
listen: tcp://127.0.0.1:6001

server:
command: "php worker.php"

temporal:
address: "127.0.0.1:7233"

logs:
level: info

Install Temporal CLI and start the development server​

The fastest way to get a development version of the Temporal Service running on your local machine is to use Temporal CLI.

Choose your operating system to install Temporal CLI:

Install the Temporal CLI using Homebrew:

brew install temporal

DLoad package manager​

Consider using DLoad to delegate all installation and updating processes to the package manager.

Add one more download action to the configuration file

<download software="temporal" version="^1.5"/>

The final configuration file should look like this:

<?xml version="1.0"?>
<dload xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:noNamespaceSchemaLocation="vendor/internal/dload/dload.xsd"
     temp-dir="./runtime"
>
  <actions>
      <download software="rr" version="^2025.1.6"/>
      <download software="temporal" version="^1.5"/>
  </actions>
</dload>

Start the development server​

Once you've installed Temporal CLI and added it to your PATH, open a new Terminal window and run the following command.

This command starts a local Temporal Service. It starts the Web UI, creates the default Namespace, and uses an in-memory database.

The Temporal Service will be available on localhost:7233. The Temporal Web UI will be available at http://localhost:8233.

Leave the local Temporal Service running as you work through tutorials and other projects. You can stop the Temporal Service at any time by pressing CTRL+C.

Once you have everything installed, you're ready to build apps with Temporal on your local machine.

After installing, open a new Terminal. Keep this running in the background:

temporal server start-dev

Change the Web UI port

The Temporal Web UI may be on a different port in some examples or tutorials. To change the port for the Web UI, use the --ui-port option when starting the server:

temporal server start-dev --ui-port 8080

The Temporal Web UI will now be available at http://localhost:8080.

Run Hello World: Test Your Installation​

Now let's verify your setup is working by creating and running a complete Temporal application with both a Workflow and Activity.

This test will confirm that:

  • The Temporal PHP SDK is properly installed
  • Your local Temporal Service is running
  • You can successfully create and execute Workflows and Activities
  • The communication between components is functioning correctly

1. Create the Activity implementation​

Create an Activity implementation file (src/GreetingActivity.php):

<?php
declare(strict_types=1);

namespace App;

use Temporal\Activity\ActivityInterface;
use Temporal\Activity\ActivityMethod;

#[ActivityInterface]
class GreetingActivity
{
    #[ActivityMethod]
    public function greet(string $name): string
    {
        return "Hello, $name!";
    }
}

An Activity is a method that executes a single, well-defined action (either short or long-running), which often involves interacting with the outside world, such as sending emails, making network requests, writing to a database, or calling an API, which is prone to failure. If an Activity fails, Temporal automatically retries it based on your configuration.

You define Activities in PHP as classes annotated with the Temporal\Activity\ActivityInterface attribute.

Each method used in workflow classes should be annotated with Temporal\Activity\ActivityMethod.

2. Create the Workflow Implementation​

Create a Workflow implementation file (src/SayHelloWorkflow.php):

<?php
declare(strict_types=1);

namespace App;

use Temporal\Activity\ActivityOptions;
use Temporal\Workflow;
use Temporal\Workflow\WorkflowInterface;
use Temporal\Workflow\WorkflowMethod;

#[WorkflowInterface]
class SayHelloWorkflow
{
    #[WorkflowMethod]
    public function sayHello(string $name)
    {
        $activity = Workflow::newActivityStub(
            GreetingActivity::class,
            ActivityOptions::new()
                ->withStartToCloseTimeout(5),
        );

        return yield $activity->greet($name);
    }
}

3. Create Worker​

Create a Worker file (worker.php, under project root directory):

<?php
declare(strict_types=1);

use Temporal\WorkerFactory;

ini_set('display_errors', 'stderr');
require "vendor/autoload.php";

$factory = WorkerFactory::create();

$worker = $factory->newWorker();

// Register Workflows
$worker->registerWorkflowTypes(\App\SayHelloWorkflow::class);
// Register Activities
$worker->registerActivity(\App\GreetingActivity::class);

$factory->run();

4. Run the Worker​

Previously, we created a Worker that executes Workflow and Activity tasks.

Now, start the RoadRunner application server to run the Worker:

./rr serve

A Worker polls a Task Queue, that you configure it to poll, looking for work to do. Once the Worker dequeues a Workflow or Activity task from the Task Queue, it then executes the task.

Workers are a crucial part of your Temporal application as they're what actually execute the tasks defined in your Workflows and Activities. For more information on Workers, see Understanding Temporal and a deep dive into Workers.

5. Execute the Workflow​

Now that your Worker is running, it's time to start a Workflow Execution.

This final step will validate that everything is working correctly with your file labeled client.php.

Create a separate file called client.php:

<?php
declare(strict_types=1);

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

ini_set('display_errors', 'stderr');
require "vendor/autoload.php";

$client = new WorkflowClient(
    ServiceClient::create('localhost:7233'),
);

$workflowStub = $client->newWorkflowStub(\App\SayHelloWorkflow::class);
$result = $workflowStub->sayHello('Temporal');

echo "Result: {$result}\n";

While your Worker is still running, open a new terminal and run:

php client.php

Verify Success​

If everything is working correctly, you should see:

  • Worker processing the workflow and activity
  • Output: Result: Hello, Temporal!
  • Workflow Execution details in the Temporal Web UI

Next: Run your first Temporal Application

Create a basic Workflow and run it with the Temporal PHP SDK

→