Roadrunner Http Laravel Package

Getting Started

Start by installing the package via Composer alongside spiral/roadrunner (typically as part of a RoadRunner-based PHP application stack). Your main entry point (public/index.php or similar) should bootstrap RoadRunner’s HTTP worker, which spiral/roadrunner-http powers behind the scenes. The first practical use case is wiring a PSR-15-compatible middleware stack or a custom request handler to RoadRunner’s worker loop—e.g., using Spiral\RoadRunner\Http\Worker to read HTTP requests from RoadRunner’s stdin and send responses back over stdout.

Implementation Patterns

• Middleware Integration: Use spiral/roadrunner-http’s Request and Response classes (PSR-7 compliant) in conjunction with PSR-15 middleware or PSR-17 factories. Common pattern: wrap application logic (e.g., Laravel/Lumen or custom controllers) in a handler that receives RoadRunner’s native request and returns a PSR-7 response.
• Streaming Responses: Leverage Spiral\RoadRunner\Http\StreamFactory to create efficient stream wrappers (e.g., for large file downloads or SSE), avoiding memory bloat.
• Worker Lifecycle Management: Hook into Worker::respond() to add timing, logging, or custom headers, or use Worker::cleanup() for per-request cleanup logic.
• Ecosystem Alignment: If using Spiral Framework, combine with spiral/roadrunner-bridge for automatic provider bootstrapping; for Laravel, integrate via custom App\Handlers\HttpHandler using RoadRunner’s worker loop.

Gotchas and Tips

• Request Body Re-reading: RoadRunner reuses the request stream; calling $request->getBody()->getContents() multiple times may return empty strings unless rewound (always use $request->getBody()->tell() === 0 or $request->getBody()->rewind() before reading).
• Missing PSR-17 Factories: While the package exposes PSR-7 types, it does not ship with PSR-17 implementations—ensure your app provides them (e.g., nyholm/psr7 + guzzlehttp/psr7 or Symfony’s PSR-17 implementation).
• Worker Loop Pitfall: Direct echo/print statements bypass the HTTP worker and can corrupt the protocol—always send responses via Worker::respond() or its async variants.
• Debugging Tip: Enable RoadRunner’s http.debug = true in .rr.yaml to log incoming requests and responses—very useful for mismatched headers or stream errors.
• Extending Behavior: Use Worker::setErrorHandler() or implement Spiral\RoadRunner\Http\WorkerInterface to inject custom behavior (e.g., tracing, metrics) without forking the core.