php quickstart

docs/develop/php/index.mdx

@@ -20,6 +20,7 @@ Build Temporal Applications with the PHP SDK.
 
 **Temporal PHP Technical Resources:**
 
+- [PHP SDK Quickstart - Setup Guide](https://docs.temporal.io/develop/php/set-up-your-local-php)
 - [PHP API Documentation](https://php.temporal.io)
 - [PHP SDK Code Samples](https://github.com/temporalio/samples-php)
 - [PHP SDK GitHub](https://github.com/temporalio/sdk-php)

docs/develop/php/set-up.mdx

@@ -0,0 +1,379 @@
+---
+id: set-up-your-local-php
+title: Set up your local with the PHP SDK
+sidebar_label: Quickstart - Setup
+description: Configure your local development environment to get started developing with Temporal
+keywords:
+  - set up
+  - getting started
+  - PHP sdk
+tags:
+  - PHP guide
+  - setup
+  - getting started
+hide_table_of_contents: true
+---
+
+import { SetupSteps, SetupStep, CodeSnippet } from "@site/src/components/elements/SetupSteps";
+import { CallToAction } from "@site/src/components/elements/CallToAction";
+
+# Quickstart - Setup
+
+Configure your local development environment to get started developing with Temporal.
+
+<SetupSteps>
+<SetupStep code={
+  <>
+    <CodeSnippet language="bash">
+    mkdir helloworld-temporalphp && cd helloworld-temporalphp
+    </CodeSnippet>
+  </>
+}>
+## Create your project directory
+
+First, create and navigate into your project directory:
+
+</SetupStep>
+
+<SetupStep code={
+<>
+<CodeSnippet language="bash">
+composer require temporal/sdk
+</CodeSnippet>
+</>
+}>
+
+## Install the Temporal PHP SDK
+
+Install the PHP SDK using Composer:
+
+If you don't already have Composer installed, you can install it using Homebrew on macOS:
+Or, [follow these instructions](https://getcomposer.org/download/) on the Composer website for Linux or Windows.
+
+</SetupStep>
+
+<SetupStep code={
+<>
+
+<p>See the <a href="https://github.com/roadrunner-server/roadrunner/blob/master/README.md" target="_blank">RoadRunner README file</a> for installation instructions.</p>
+
+<p>Using Composer, you can install it with the following command:</p>
+<CodeSnippet language="bash">
+composer require spiral/roadrunner-cli
+./vendor/bin/rr get-binary
+</CodeSnippet></>
+}>
+
+## Download RoadRunner
+
+See the RoadRunner README file for installation instructions.
+When prompted, enter yes to generate a default `.rr.yaml` file.
+You’ll update it later to configure the Temporal plugin.
+
+Next, you'll configure a local Temporal Service for development.
+
+</SetupStep>
+
+<SetupStep code={
+<>
+<Tabs>
+<TabItem value="macos" label="macOS" default>
+
+        <p>Install the Temporal CLI using Homebrew:</p>
+        <CodeSnippet language="bash">
+        brew install temporal
+        </CodeSnippet>
+      </TabItem>
+
+      <TabItem value="windows" label="Windows">
+        <p>Download the Temporal CLI archive for your architecture:</p>
+        <ul>
+          <li><a href="https://temporal.download/cli/archive/latest?platform=windows&arch=amd64">Windows amd64</a></li>
+          <li><a href="https://temporal.download/cli/archive/latest?platform=windows&arch=arm64">Windows arm64</a></li>
+        </ul>
+        <p>Extract it and add <code>temporal.exe</code> to your PATH.</p>
+      </TabItem>
+
+      <TabItem value="linux" label="Linux">
+        <p>Download the Temporal CLI for your architecture:</p>
+        <ul>
+          <li><a href="https://temporal.download/cli/archive/latest?platform=linux&arch=amd64">Linux amd64</a></li>
+          <li><a href="https://temporal.download/cli/archive/latest?platform=linux&arch=arm64">Linux arm64</a></li>
+        </ul>
+        <p>Extract the archive and move the <code>temporal</code> binary into your PATH, for example:</p>
+        <CodeSnippet language="bash">
+        sudo mv temporal /usr/local/bin
+        </CodeSnippet>
+      </TabItem>
+    </Tabs>
+
+</>
+}>
+
+## 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](https://docs.temporal.io/cli).
+
+Choose your operating system to install Temporal CLI:
+
+</SetupStep>
+<SetupStep code={
+  <>
+    <CodeSnippet language="yaml">
+{`version: "3"
+
+rpc:
+listen: tcp://127.0.0.1:6001
+
+server:
+command: "php -d display_errors=stderr src/worker.php"
+
+temporal:
+address: \${TEMPORAL_HOST:-localhost}:\${TEMPORAL_PORT:-7233}
+activities:
+num_workers: 4
+
+logs:
+level: info
+mode: development`}
+</CodeSnippet>
+</>
+}>
+
+## Create a RoadRunner configuration file
+
+To configure RoadRunner Temporal plugin create or open the `.rr.yaml` file in your project directory and make sure it contains the following:
+
+Replace the default contents of your `.rr.yaml` file with the following configuration, which is required to run the Temporal Worker:
+This example shows a minimal <code>.rr.yaml</code> configuration specifically for running a Temporal Worker.
+
+</SetupStep>
+
+<SetupStep code={
+<>
+
+<p>After installing, open a new Terminal window and start the development server:</p>
+<CodeSnippet language="bash">
+temporal server start-dev
+</CodeSnippet>
+
+<div className="port-info">
+<h4>Change the Web UI port</h4>
+<p>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 <code>--ui-port</code> option when starting the server:</p>
+<CodeSnippet language="bash">
+temporal server start-dev --ui-port 8080
+</CodeSnippet>
+<p>The Temporal Web UI will now be available at http://localhost:8080.</p>
+</div>
+<style>
+{`.port-info { background: rgba(68, 76, 231, 0.1); border: 1px solid rgba(68, 76, 231, 0.2); border-radius: 0.75rem; padding: 1.5rem; margin: 1.5rem 0; transition: all 0.3s ease-in-out; box-shadow: 0 2px 4px rgba(0, 0, 0, 0.05); } [data-theme='dark'] .port-info { background: rgba(68, 76, 231, 0.15); border-color: rgba(68, 76, 231, 0.3); } .port-info h4 { margin-top: 0; margin-bottom: 1rem; color: var(--ifm-color-emphasis-900); font-weight: 600; } .port-info p { margin-bottom: 1rem; font-size: 0.95rem; line-height: 1.5; color: var(--ifm-color-emphasis-800); } .port-info p:last-child { margin-bottom: 0; } .port-info code { background: rgba(255, 255, 255, 0.5); padding: 0.2rem 0.4rem; border-radius: 4px; font-size: 0.9em; } [data-theme='dark'] .port-info code { background: rgba(0, 0, 0, 0.2); } @media (max-width: 768px) { .port-info { padding: 1.25rem; } }`}
+</style>
+</>
+}>
+
+## 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.
+
+</SetupStep>
+</SetupSteps>
+
+## 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:
+
+- Your PHP SDK installation is working
+- 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 Interface
+
+Create an Activity Interface file (GreetingActivityInterface.php) in an Activities subdirectory:
+
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace App\Activities;
+
+use Temporal\Activity\ActivityInterface;
+use Temporal\Activity\ActivityMethod;
+
+#[ActivityInterface]
+interface GreetingActivityInterface
+{
+    #[ActivityMethod]
+    public function greet(string $name): string;
+}
+```
+
+### 2. Create the Activity Implementation
+
+An Activity is a normal function or method that executes a single, well-defined action (either short or long running), which often involve interacting with the outside world, such as sending emails, making network requests, writing to a database, or calling an API, which are prone to failure. If an Activity fails, Temporal automatically retries it based on your configuration.
+
+Create an Activity implementation file (GreetingActivity.php) in the Activities subdirectory:
+
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace App\Activities;
+
+class GreetingActivity implements GreetingActivityInterface
+{
+    public function greet(string $name): string
+    {
+        return "Hello {$name}";
+    }
+}
+```
+
+### 3. Create the Workflow Interface
+
+Create a Workflow Interface file (SayHelloWorkflowInterface.php) in a Workflows subdirectory:
+
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace App\Workflows;
+
+use Temporal\Workflow\WorkflowInterface;
+use Temporal\Workflow\WorkflowMethod;
+
+#[WorkflowInterface]
+interface SayHelloWorkflowInterface
+{
+    #[WorkflowMethod]
+    public function sayHello(string $name): \Generator;
+}
+```
+
+### 4. Create the Workflow Implementation
+
+Workflows orchestrate Activities and contain the application logic. Temporal Workflows are resilient. They can run—and keeping running—for years, even if the underlying infrastructure fails. If the application itself crashes, Temporal will automatically recreate its pre-failure state so it can continue right where it left off.
+
+Create a Workflow implementation file (SayHelloWorkflow.php) in the Workflows subdirectory:
+
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace App\Workflows;
+
+use App\Activities\GreetingActivityInterface;
+use Temporal\Workflow;
+use Temporal\Activity\ActivityOptions;
+use Carbon\CarbonInterval;
+
+class SayHelloWorkflow implements SayHelloWorkflowInterface
+{
+    public function sayHello(string $name): \Generator
+    {
+        $activity = Workflow::newActivityStub(
+            GreetingActivityInterface::class,
+            ActivityOptions::new()
+                ->withScheduleToCloseTimeout(CarbonInterval::seconds(10))
+        );
+
+        return yield $activity->greet($name);
+    }
+}
+```
+
+### 5. Create and Run the Worker
+
+With your Activity and Workflow defined, you need a Worker to execute them. A Worker polls a Task Queue, that you configure it to poll, looking for work to do. Once the Worker dequeues the a Workflow or Activity task from the Task Queue, it then executes that 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](/evaluate/understanding-temporal#workers) and a [deep dive into Workers](/workers).
+
+Create a Worker file (worker.php):
+
+```php
+<?php
+
+declare(strict_types=1);
+
+use Temporal\WorkerFactory;
+
+require __DIR__ . '/vendor/autoload.php';
+
+$factory = WorkerFactory::create();
+$worker = $factory->newWorker();
+
+$worker->registerWorkflowTypes(\App\Workflows\SayHelloWorkflow::class);
+$worker->registerActivityImplementations(new \App\Activities\GreetingActivity());
+
+$factory->run();
+```
+
+Run the Worker:
+
+```bash
+php worker.php
+```
+
+### 6. Execute the Workflow
+
+Now that your Worker is running, it's time to start a Workflow Execution.
+
+Create a separate file called starter.php:
+
+```php
+<?php
+
+declare(strict_types=1);
+
+use Temporal\Client\WorkflowClient;
+use Temporal\Client\WorkflowOptions;
+
+require __DIR__ . '/vendor/autoload.php';
+
+$workflowClient = WorkflowClient::create('localhost:7233');
+
+$workflow = $workflowClient->newWorkflowStub(
+    \App\Workflows\SayHelloWorkflowInterface::class,
+    WorkflowOptions::new()
+        ->withWorkflowId('say-hello-workflow-id')
+        ->withTaskQueue('my-task-queue')
+);
+
+$result = $workflow->sayHello('Temporal');
+echo "Workflow result: " . $result . PHP_EOL;
+```
+
+Then run:
+
+```bash
+php starter.php
+```
+
+### Verify Success
+
+If everything is working correctly, you should see:
+
+- Worker processing the Workflow and Activity
+- Output: `Workflow result: Hello Temporal`
+- Workflow Execution details in the [Temporal Web UI](http://localhost:8233)
+
+<CallToAction href="https://learn.temporal.io/getting_started/php/hello_world_in_php/">
+  <h3>Next: Run your first Temporal Application</h3>
+  <p>Learn how to create a basic Workflow and run it with the Temporal PHP SDK</p>
+</CallToAction>

sidebars.js

@@ -176,6 +176,7 @@ module.exports = {
             id: "develop/php/index",
           },
           items: [
+            "develop/php/set-up-your-local-php",
             "develop/php/core-application",
             "develop/php/temporal-clients",
             "develop/php/testing-suite",