Roadrunner Worker Laravel Package

Getting Started

• Install via Composer: composer require spiral/roadrunner-worker
• Initialize a basic worker by extending Spiral\RoadRunner\Worker and implementing a request loop:

  use Spiral\RoadRunner\Worker;
  
  require __DIR__ . '/vendor/autoload.php';
  
  $worker = new Worker();
  while ($req = $worker->waitRequest()) {
      try {
          $payload = json_decode($req->getPayload(), true);
          $response = ['result' => 'Handled: ' . ($payload['action'] ?? 'unknown')];
          $worker->respond($response);
      } catch (\Throwable $e) {
          $worker->error((string)$e);
      }
  }
  

• Configure .rr.yaml to point to your worker script (exec: php worker.php)
• Start RoadRunner: ./rr serve
• First use case: Process background jobs or long-running HTTP requests with persistent application state (e.g., queue consumers, HTTP microservices)

Implementation Patterns

• Separate worker types: Create dedicated workers for different job queues (QueueWorker, HttpWorker) by checking request headers (e.g., rr-worker-type) or payload structure
• Dependency injection: Boot your DI container outside the loop and reuse services inside it for performance:

  $container = buildContainer(); // expensive setup once
  while ($req = $worker->waitRequest()) {
      $handler = $container->get(SomeHandler::class);
      $handler->handle($req);
  }
  

• Job dispatching: Wrap payloads in PSR-7/18 style objects (e.g., Spiral\RoadRunner\PSR7Client) and pass to Symfony Messenger or Laravel Queue for unified processing
• Graceful shutdown: Use $worker->isStopRequested() in the loop to respond to RoadRunner’s /stop signal and flush pending work before exiting
• Metrics & logging: Integrate with PSR-3 logger; emit metrics via ext-ffi or ext-prometheus before respond() for observability

Gotchas and Tips

• Memory leaks: Avoid storing request-specific data in static properties—leak over time. Use instance variables inside the loop scope, or explicitly clear them per request
• Uncaught exceptions: RoadRunner will terminate the worker if unhandled exceptions escape the loop. Always wrap processing in try/catch and use $worker->error($msg) for non-fatal issues
• Payload format mismatches: RoadRunner may send Psr\Http\Message\ServerRequestInterface (via spiral/roadrunner-http) or raw strings (via spiral/roadrunner-queue). Decode appropriately using $req->getPayload() or cast to PSR if available
• Debugging: Enable RR_DEBUG=1 and check RoadRunner logs (./rrserve -d) to see worker communication
• Extension points: Leverage Spiral\RoadRunner\Environment to externalize config; override Worker methods like respond() for custom serialization (e.g., JSON to MessagePack)
• Version mismatch: spiral/roadrunner-worker v3+ requires RoadRunner v2. Ensure Spiral\RoadRunner\Version::VERSION matches RoadRunner binary version at runtime—use RR_VERSION env for validation