Roadrunner Bridge Laravel Package

Getting Started

1. Install the package via Composer: composer require spiral/roadrunner-bridge
2. Install RoadRunner binary: Download the appropriate release for your OS from RoadRunner’s GitHub releases and place it in your $PATH.
3. Bootstrap your app by replacing your standard public/index.php with the bridge’s entrypoint (vendor/spiral/roadrunner-bridge/bin/roadrunner.php), or integrate the bridge’s HttpKernel via custom routing if you prefer minimal changes.
4. First run: Start RoadRunner with ./rr serve -d, which loads your Laravel app in persistent worker mode—no php-fpm or Apache needed.

Implementation Patterns

• Long-lived request lifecycle: Replace traditional PHP-FPM per-request bootstrapping with persistent service containers—only reinitialize on config changes or manual reload (./rr worker/restart).
• Custom workers: Define event listeners or queue consumers as RoadRunner workers (e.g., Spiral\RoadRunnerBridge\Queue\Worker) to handle jobs without reloading Laravel each time—great for high-throughput job processing.
• Runtime config via .rr.yaml: Place RoadRunner config adjacent to .env (e.g., .rr.yaml):

  http:
    address: 0.0.0.0:8080
    pool:
      num_workers: 4
      max_jobs: 0  # infinite lifecycle
  workers:
    command: "php public/index.php"
  

• Middleware integration: Leverage Laravel middleware cleanly—only boot() and terminate() callbacks run per-request; all service bindings persist.
• Hot reload dev workflow: Use ./rr serve -d -e=debug with file watchers to auto-reload PHP code on changes during development.

Gotchas and Tips

• State awareness is critical: Persistent workers retain database connections and static state across requests. Use terminate() callbacks (from Spiral\RoadRunnerBridge\Terminate\Terminator) or Laravel’s Event::listen(Shutdown::class, ...) to clear caches, reset DB connections, or close sockets.
• .env overrides: RoadRunner doesn’t read .env during runtime unless explicitly triggered. Ensure APP_ENV and other critical vars are baked into config during build or passed via --env flag.
• Debugging: Enable RoadRunner logging (log.output: stderr, log.level: debug) to trace request routing and worker state; use dd() only in workers for isolated requests—output goes to RoadRunner logs, not CLI.
• Extension points: Extend Spiral\RoadRunnerBridge\Bootstrap\Bootstrapper to customize Laravel bootstrap (e.g., lazy service loading, custom config merging).
• Deployment tip: Pre-warm Laravel’s cache (config:cache, route:cache) before starting RoadRunner—persistent workers cannot recompile caches at runtime.
• Memory leaks: Monitor worker memory via memory_get_usage(true). If using Doctrine or long-lived ORM connections, manually clear unit-of-work or reconnect periodically (max_jobs > 0).