Roadrunner Jobs Laravel Package

Getting Started

1. Install the package via Composer: composer require spiral/roadrunner-jobs.
2. Configure your queue driver in config/queue.php (or equivalent) to use roadrunner as the driver.
3. Set up RoadRunner with the jobs plugin enabled in your .rr.yaml or rr.yaml config (e.g., jobs: { pools: { default: { num_workers: 4, worker_options: { max_jobs: 10000 } } } }).
4. Bootstrap RoadRunner with your Laravel app using php artisan roadrunner:reset (if using Spiral’s RoadRunner integration) or start RoadRunner via ./rr serve.
5. First use case: Dispatch a job (e.g., MailJob::dispatch(...))—it’s consumed by a persistent RoadRunner worker instead of a short-lived PHP-FPM process.

📌 Start here: Check the official RoadRunner docs for Laravel and inspect spiral/roadrunner-jobs’ config/queue.php snippet in the repo’s README.

Implementation Patterns

• Standard job dispatching remains unchanged — use dispatch(), dispatchNow(), or dispatchIf() as usual; roadrunner-jobs transparently intercepts the queue driver.
• Configure pipelines in .rr.yaml to control concurrency, memory limits, and worker lifecycle:

  jobs:
    pools:
      default:
        num_workers: 4
        worker_options:
          max_jobs: 5000
          memory_limit: 256M
          pipeline: "default" # maps to a named pipeline config below
    pipelines:
      default:
        route: default
        priority: 0
  

• Use queue topics (e.g., default, emails, billing) by specifying the queue in your job’s viaQueue() method or dispatch(...)->onQueue('emails'). Configure topic mapping in .rr.yaml:

  topics:
    emails:
      num_workers: 8
    billing:
      num_workers: 2
  

• Monitor & scale: RoadRunner exposes metrics via HTTP (e.g., /metrics). Use container orchestration (Kubernetes, Docker Swarm) to scale worker replicas horizontally based on queue depth.
• Error handling: Leverage Laravel’s native FailedJobProvider—failed jobs are still stored in your configured failed_jobs table. RoadRunner handles retries within the worker via config (retry_until in worker_options).

Gotchas and Tips

• 🔥 Worker memory leaks: Long-lived workers accumulate memory over time. Always set max_jobs or max_execution_time in .rr.yaml to restart workers gracefully. Tip: Monitor RR_WORKER_ID in logs to detect restarts.
• ⚠️ Database connections: Persistent workers reuse PDO/PDO-like connections. Always use DB::reconnect() or DB::purge() in Job::finally() or handle() if long-running jobs risk stale connections.
• 🧩 Custom job serialization: RoadRunner uses JSON by default. Avoid large payloads (>1MB) — they cause pipeline backpressure. Tip: Store payloads in S3 and pass signed URLs.
• 🔁 Restart during deployments: Use roadrunner:reset (via Laravel Horizon alternative) or send SIGHUP to the RoadRunner process to reload workers without downtime. Avoid kill -9.
• 📦 Extension point: Implement Spiral\RoadRunner\Jobs\JobHandlerInterface for custom job handling (e.g., for PSR-14 events or complex event sourcing).
• 🐛 Debugging: Enable debug: true in .rr.yaml and check RoadRunner logs (stderr or logs/rr.log) for pipeline errors (e.g., {"level":"error","msg":"job failed","error":"class not found"}).
• 📦 Package size: With only ~27 stars, it’s lightweight and focused—but verify compatibility with your Laravel/RoadRunner versions (last release 2025-11-05 suggests active maintenance).