Roadrunner Http Laravel Package

Getting Started

Install via Composer using the new package name — as of v4.2.0 the package is published as roadrunner/http (it was previously spiral/roadrunner-http):

composer require roadrunner/http

Two things to check immediately after bumping:

1. PHP 8.2+ is now required. If your app is still on 8.1, pin ^4.1 until you upgrade.
2. RoadRunner v3 is now supported. Update your .rr.yaml (RoadRunner 3 expects version: '3' and the http.pool/server key layout) and your binary/rr CLI to a v3 release before rolling this out.

The package remains a thin PSR-7 bridge over the RoadRunner worker loop, so the PHP namespace you use in code is still Spiral\RoadRunner\Http\* (PSR7Worker, Request, Response, StreamFactory) — verify with composer show roadrunner/http and the refreshed README if your autoloader complains after the rename.

First use case in a Laravel app: you almost certainly don't call this package directly. Install laravel/octane and select the RoadRunner driver (php artisan octane:install --server=roadrunner), which wires PSR7Worker into public/index.php for you. Reach for the package directly only when you need a custom worker bootstrap or you're writing a standalone non-Octane service.

Implementation Patterns

• Octane is the day-to-day path. php artisan octane:start --server=roadrunner --watch gives you the worker loop; the package supplies the PSR7Worker that converts RoadRunner payloads into Psr\Http\Message\ServerRequestInterface and hands back a PSR-7 response. Your job is keeping controllers/services stateless and container bindings flushable.
• Manual worker bootstrap (non-Octane or custom loop): instantiate PSR7Worker with the RoadRunner worker + PSR-17 factories, then while ($request = $worker->waitRequest()) → pass to your kernel → $worker->respond($response). Wrap the kernel call in try/catch and respond with a 500 rather than letting the exception kill the worker silently.
• PSR-17 factories are required by you. PSR7Worker takes Psr\Http\Message\ResponseFactoryInterface and StreamFactoryInterface in its constructor — nyholm/psr7 is the lightweight default, guzzlehttp/psr7 if you already ship it. Laravel's default HttpFoundation stack does not provide PSR-7, so don't assume it's there.
• Streaming responses. Use the package's stream factory for large downloads and SSE; the point is to avoid materialising the body in memory per worker. Combine with octane's response handling carefully — buffered Octane responses still load the body.
• Middleware / lifecycle hooks. For cross-cutting concerns in a hand-rolled worker (timing, tracing, metrics, security headers), decorate around waitRequest()/respond() rather than forking the worker. In Octane, prefer Octane::tick() / listeners and app('events') hooks.
• RoadRunner v3 config. Put worker tuning under http.pool (num_workers, max_jobs, allocate_timeout, destroy_timeout) and keep http.middleware (static, gzip, headers) in .rr.yaml so PHP never parses those requests.
• Ecosystem alignment: Laravel/Lumen → Octane; Spiral Framework → spiral/roadrunner-bridge handles provider bootstrapping automatically.

Gotchas and Tips

• The rename breaks naive tooling. composer require spiral/roadrunner-http now resolves the old, unmaintained line. Update composer.json, any Dockerfiles pinning the old name, and CI caches. If you have a replace/provide entry or a Composer patch, re-check it.
• Upgrade PHP and RoadRunner together. v4.2.0 requires PHP 8.2 and targets RoadRunner v3. A half-done upgrade (PHP 8.2 but rr v2, or vice versa) tends to surface as opaque worker-restart loops rather than a clear error — read rr serve -v output first.
• Request body re-reading. The request stream is consumed once; if middleware and controller both read it, call $request->getBody()->rewind() (or check tell() === 0) before the second read, or capture the contents early.
• Never echo/print/var_dump in a worker. Anything on stdout corrupts the RoadRunner protocol and shows up as a garbled response or a killed worker. Use logger() (RoadRunner RPC) or Laravel's log channel; use dump()/dd() only with Octane's debug tooling enabled.
• Numeric header names now survive filterHeaders() (fixed in v4.2.0). Headers like 0 or 123 used to be dropped, which broke some webhook/proxy signatures. Remove any workaround you added that prefixed such headers with a string.
• Debugging: http.debug: true in .rr.yaml logs request/response pairs — best first move for header mismatches and empty-body reports. For Octane, php artisan octane:status and the worker logs distinguish "application error" from "worker died".
• State leakage under Octane. Singletons capturing request data, static caches, and unclosed DB transactions cause bugs that only appear under concurrency. Add Octane::tick() cleanup or reset bindings in config/octane.php's warm/flush arrays.
• #[\Override] everywhere — harmless to consumers, but if you subclass PSR7Worker or the Request/Response classes, ensure your method signatures still match; a mismatch now fails at class-load with a clearer fatal error instead of a silent mismatch.
• Extension points: PSR7Worker accepts custom PSR-17 factories and error handling around waitRequest(); for deeper hooks (metrics, tracing) prefer decorating the worker or handling it at the RoadRunner middleware/RPC layer rather than patching the package.