Sdk Laravel Package

Getting Started

Minimal Setup

1. Install the SDK:

   composer require temporal/sdk
   

   Ensure your composer.json includes "temporal/sdk": "^x.y.z" (check releases).

2. Configure the Client: Add Temporal server connection details to your .env:

   TEMPORAL_SERVER_URL=temporal://localhost:7233
   TEMPORAL_NAMESPACE=default
   

   Initialize the client in a service provider (e.g., AppServiceProvider):

   use Temporal\Client;
   
   $client = Client::create([
       'connection' => [
           'address' => env('TEMPORAL_SERVER_URL'),
       ],
   ]);
   

3. First Workflow Execution: Define a simple workflow and activity:

   // app/Workflows/HelloWorkflow.php
   use Temporal\Workflow;
   
   Workflow::define('hello-workflow', function () {
       $result = Workflow::executeActivity('say-hello', ['name' => 'World']);
       return $result;
   });
   
   // app/Activities/SayHello.php
   use Temporal\Activity;
   
   Activity::define('say-hello', function (string $name) {
       return "Hello, {$name}!";
   });
   

4. Run a Worker: Start a worker in a console command (e.g., php artisan temporal:workers):

   use Temporal\Worker;
   use Temporal\WorkerFactory;
   
   $factory = WorkerFactory::create($client);
   $worker = $factory->createWorker('default-task-queue');
   $worker->registerWorkflowTypes([HelloWorkflow::class]);
   $worker->registerActivityTypes([SayHello::class]);
   $worker->run();
   

5. Trigger the Workflow: Use the client to start the workflow:

   $handle = $client->workflowService()->startWorkflow(
       'hello-workflow',
       [],
       ['taskQueue' => 'default-task-queue']
   );
   $result = $handle->getResult();
   

Key Resources

• Temporal PHP SDK Docs
• Workflows vs. Activities
• Temporal CLI for local testing.

Implementation Patterns

Core Workflows

1. Workflow Design:

   • Use Workflow::define() for declarative workflows.
   • Leverage child workflows for modularity:

     Workflow::define('parent-workflow', function () {
         $childResult = Workflow::executeChildWorkflow('child-workflow', []);
         return "Parent: {$childResult}";
     });
     

   • Signal handling for external interruptions:

     Workflow::onSignal('pause', function () {
         Workflow::sleep(1000); // Pause execution
     });
     

2. Activity Patterns:

   • Retry policies: Configure retries for transient failures:

     Activity::define('faulty-activity', function () {
         // ...
     }, ['retry' => ['maximumAttempts' => 3, 'interval' => '1s']]);
     

   • Heartbeats: For long-running activities:

     Activity::define('long-running-task', function () {
         while (true) {
             Workflow::heartbeat('Still running...');
             sleep(1);
         }
     });
     

3. Workflow Execution:

   • Fan-out/fan-in for parallel tasks:

     $promises = [];
     foreach ($tasks as $task) {
         $promises[] = Workflow::executeActivity('process-task', [$task]);
     }
     return Workflow::allOf($promises);
     

   • Workflow queries for real-time state checks:

     Workflow::define('trackable-workflow', function () {
         $this->query('status', function () {
             return $this->status;
         });
     });
     

Integration with Laravel

1. Service Container Binding: Bind the client/worker factory in AppServiceProvider:

   $this->app->singleton(Client::class, function ($app) {
       return Client::create(['connection' => ['address' => env('TEMPORAL_SERVER_URL')]]);
   });
   

2. Artisan Commands: Create a command to manage workers:

   // app/Console/Commands/RunTemporalWorkers.php
   use Illuminate\Console\Command;
   use Temporal\WorkerFactory;
   
   class RunTemporalWorkers extends Command
   {
       protected $signature = 'temporal:workers';
       public function handle()
       {
           $factory = WorkerFactory::create(app(Client::class));
           $worker = $factory->createWorker('default-task-queue');
           $worker->registerWorkflowTypes([HelloWorkflow::class]);
           $worker->run();
       }
   }
   

3. Queues as Fallback: Use Laravel queues for non-critical tasks while offloading complex orchestration to Temporal:

   // Dispatch a workflow instead of a queue job
   $handle = app(Client::class)->workflowService()->startWorkflow(
       'process-order',
       ['orderId' => $order->id],
       ['taskQueue' => 'orders']
   );
   

4. Event Listeners: Trigger workflows from Laravel events:

   // app/Listeners/StartOrderWorkflow.php
   use Temporal\Client;
   
   public function handle(OrderCreated $event)
   {
       $client = app(Client::class);
       $client->workflowService()->startWorkflow(
           'process-order',
           ['orderId' => $event->order->id],
           ['taskQueue' => 'orders']
       );
   }
   

Gotchas and Tips

Common Pitfalls

1. Serialization Issues:

   • Temporal serializes workflow/activity arguments. Avoid:
     • Closures, resources, or non-serializable objects (e.g., database connections).
     • Use DTOs or arrays for arguments.
   • Fix: Implement JsonSerializable or use Temporal\Payloads.

2. Worker Registration:

   • Forgetting to register workflow/activity types with the worker:

     // ❌ Missing registration
     $worker->run(); // Workflows/activities won't execute!
     

   • Fix: Always call registerWorkflowTypes() and registerActivityTypes().

3. Task Queue Mismatch:

   • Workflows started with a task queue that doesn’t match the worker’s queue will never execute.
   • Fix: Ensure consistency between startWorkflow() and createWorker().

4. Workflow Timeout:

   • Default workflow timeout is 10 minutes. Long-running workflows may fail silently.
   • Fix: Configure timeouts explicitly:

     $handle = $client->workflowService()->startWorkflow(
         'long-workflow',
         [],
         ['taskQueue' => 'queue', 'workflowId' => 'unique-id', 'timeout' => '1h']
     );
     

5. Activity Heartbeats:

   • Activities without heartbeats may appear "stuck" in the Temporal UI.
   • Fix: Use Workflow::heartbeat() for long-running activities.

Debugging Tips

1. Temporal CLI:

   • Inspect workflows/activities:

     temporal workflow describe <workflow_id> --namespace <namespace>
     temporal activity list --namespace <namespace>
     

   • Search for workflows:

     temporal workflow list --namespace <namespace> --query "WorkflowType = 'hello-workflow'"
     

2. Logging:

   • Enable debug logging in the client:

     $client = Client::create([
         'connection' => ['address' => env('TEMPORAL_SERVER_URL')],
         'logger' => new Monolog\Logger('temporal', [new Monolog\Handler\StreamHandler('php://stderr')]),
     ]);
     

3. Local Testing:

   • Use Docker for local Temporal server:

     docker run -p 7233:7233 temporalio/auto-setup:latest
     

   • Buggregator: For advanced debugging (see Dev Environment).

Extension Points

1. Custom Interceptors:

   • Add middleware to workflow/activity calls:

     $client->workflowService()->addInterceptor(new CustomWorkflowInterceptor());
     

2. Signal Handling:

   • Extend workflows with custom signals:

     Workflow::define('custom-workflow', function () {
         Workflow::onSignal('custom-signal', function ($data) {
             // Handle signal
         });
     });
     

3. Activity Delegates:

   • Offload activity execution to external services:

     Activity::define('external-call', function ($