Symfony Temporal Worker Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require buyanov/symfony-temporal-worker
   

   Ensure your Laravel app uses Symfony’s dependency injection (via symfony/dependency-injection and symfony/http-kernel).

2. First Use Case: Define a Temporal Activity (e.g., ProductPropertyActivityInterface) and annotate it with:

   #[AutoconfigureTag('temporal.activity')]
   #[ActivityInterface('YourNamespace.')] // Unique prefix for activities
   

   Register the worker in config/services.php:

   'temporal' => [
       'worker' => [
           'namespace' => 'App\\Temporal\\Activity',
           'task_queue' => 'laravel-queue',
       ],
   ],
   

3. Run the Worker: Add a console command (e.g., php artisan temporal:worker) to start the Symfony-based worker:

   use Buyanov\TemporalWorker\Worker\Worker;
   
   protected function execute(InputInterface $input, OutputInterface $output): int
   {
       $worker = new Worker(
           $this->getContainer(),
           config('temporal.worker.namespace'),
           config('temporal.worker.task_queue')
       );
       $worker->run();
       return 0;
   }
   

Implementation Patterns

Workflow Integration

1. Activities:

   • Use interfaces for activities (e.g., ProductPropertyActivityInterface).
   • Annotate methods with @ActivityMethod to define Temporal’s activity names.
   • Inject activities into workflows via Symfony’s DI container.

2. Workflows:

   • Define workflows as services with @AutoconfigureTag('temporal.workflow').
   • Example:

     #[AutoconfigureTag('temporal.workflow')]
     class ProductWorkflow
     {
         public function __construct(
             private ProductPropertyActivityInterface $activity
         ) {}
     
         public function execute(string $productGuid): string
         {
             return $this->activity->createOrUpdateProductProperty(
                 $productGuid,
                 'property-guid',
                 'value'
             );
         }
     }
     

3. Task Queues:

   • Configure task_queue in config/temporal.php to match your Temporal server’s queue.
   • Use Laravel’s queue system (e.g., Redis) as a bridge if needed.

Daily Workflows

• Long-Running Tasks: Use workflows for orchestration (e.g., multi-step order processing).

  #[ActivityMethod('processOrder')]
  public function processOrder(string $orderId): void { ... }
  

• Retry Logic: Leverage Temporal’s built-in retry policies (configured via ActivityOptions).
• Signal Handling: Use Workflow::signal() to interrupt workflows (e.g., cancel orders).

Gotchas and Tips

Pitfalls

1. Namespace Collisions: Ensure @ActivityInterface prefixes are unique (e.g., App.Temporal.Product.). Overlapping prefixes cause ActivityNotFoundException.

2. Worker Registration:

   • The worker must be started manually (no auto-registration in Laravel).
   • Use php artisan temporal:worker in a separate process (e.g., Docker, PM2).

3. Dependency Injection:

   • Activities/workflows cannot use Laravel’s service providers directly.
   • Prefer Symfony’s autowiring (e.g., #[Autowire]).

4. Debugging:

   • Check Temporal’s UI (e.g., http://localhost:8080) for workflow runs.
   • Log activity failures with Temporal\Activity\ActivityOptions::setLogger().

Tips

1. Configuration: Extend config/temporal.php for custom options:

   'worker' => [
       'poll_interval' => 1000, // Milliseconds
       'max_concurrent_activities' => 10,
   ],
   

2. Testing: Use Temporal’s TestWorkflowEnvironment for unit tests:

   $env = new TestWorkflowEnvironment();
   $result = $env->executeWorkflow(new ProductWorkflow(), ['orderId']);
   

3. Laravel Integration:

   • Store Temporal’s WorkflowId in Laravel’s database for tracking.
   • Use Laravel’s events to trigger workflows (e.g., OrderCreated event).

4. Performance:

   • Batch activities where possible to reduce overhead.
   • Monitor max_concurrent_activities to avoid throttling.