Weave Code
Roadrunner Laravel Package
spiral/roadrunner
RoadRunner is a high-performance PHP application server and process manager written in Go. It offers HTTP/2/3, gRPC, fCGI, queues, KV storage, and OpenTelemetry via plugins, serving as a powerful alternative to Nginx+FPM.
RoadRunner is a high-performance, open-source (MIT) PHP application server and process manager written in Go. It runs PHP workers efficiently and acts as a drop-in alternative to the traditional Nginx + FPM stack, offering higher throughput and greater flexibility. Run it as a service and extend it per-project with plugins.
Key features:
- HTTP(S)/HTTP2/HTTP3 and FastCGI servers with PSR-7/PSR-17 support
- Queue drivers: RabbitMQ, Kafka, SQS, Beanstalk, NATS, in-memory
- KV drivers: Redis, Memcached, BoltDB, in-memory
- OpenTelemetry integration for tracing and metrics
- Go-powered process manager with graceful reloads
Frequently asked questions about Roadrunner
- What is spiral/roadrunner and how does it fit into a Laravel application?
- spiral/roadrunner is the PHP SDK for RoadRunner, an open-source application server and process manager written in Go. RoadRunner is not a Laravel package; in Laravel the realistic integration path is Laravel Octane's roadrunner driver. The Go server provides HTTP(S)/2/3 and FastCGI serving, queue and KV drivers, and OpenTelemetry, while Octane handles the Laravel worker lifecycle.
- How do I install RoadRunner for a Laravel app with Octane?
- Use php artisan octane:install --server=roadrunner to wire up Octane's RoadRunner driver and generate the .rr.yaml configuration. In production, build a multi-stage Docker image that copies /usr/bin/rr from a pinned RoadRunner image tag rather than compiling the Go binary yourself. Make sure the sockets PHP extension is installed in the image, and keep a CI boot smoke test that starts the server and issues a request.
- Is spiral/roadrunner a Laravel package I can use directly?
- No. RoadRunner is a Go application server plus a thin PHP SDK, and direct SDK use only makes sense if you need the plugin surface such as queues, KV, gRPC, Temporal, locks, Prometheus or OpenTelemetry. For HTTP serving in Laravel, use Octane's roadrunner driver instead of wiring the SDK manually. Treat spiral/roadrunner as the transport layer rather than a drop-in Laravel feature package.
- Which Laravel and Octane versions support RoadRunner v3?
- Octane historically pins to specific RoadRunner majors and can lag behind new server releases, so you must verify compatibility before upgrading. Confirm that your Octane version's roadrunner driver supports the RoadRunner v3 wire protocol and configuration format, that the spiral/roadrunner-worker, roadrunner-http and roadrunner-cli v3 SDK packages are released, and that Symfony Runtime supports v3. If any of those is not ready, pin to the latest v2025.x release and schedule v3 as a follow-on migration.
- What performance benefits does RoadRunner offer over Nginx and PHP-FPM?
- RoadRunner amortizes Laravel bootstrapping across long-lived workers, which removes per-request framework startup cost and can substantially improve throughput. It is also a self-contained server that absorbs much of the Nginx configuration surface, including static files, gzip and zstd, headers, sendfile, TLS, rate limiting and 103 Early Hints. The trade-off is that you move from a request-scoped model to long-lived workers, which is an application-code contract change rather than a simple infrastructure swap.
- How do I prevent state leakage between requests with RoadRunner and Octane?
- State leakage between requests is the highest-severity risk with long-lived workers and is an application-correctness problem, not an infrastructure problem. Avoid storing request data in singletons, static properties or globally scoped bindings, and reset any scoped container bindings between requests. Write tests that send consecutive requests through the same worker and assert that no data from a previous request is visible.
- What configuration changes does RoadRunner v3 introduce for Laravel deployments?
- In v3, http.middleware is evaluated left to right, so v5 middleware lists must be reversed to preserve behavior, and this change is silent rather than an error. AMQP removes config.version and requires static pipelines to set config.connection plus nested exchange and queue blocks. MessagePack is removed from Goridge RPC, envfile is now non-experimental so a configured file must exist at startup, h2c is no longer supported for cleartext HTTP/2, and dynamic_allocator.max_workers now counts workers above the base pool, which invalidates earlier autoscaling numbers.
- Why does RoadRunner fail to start with EOF on worker start in Laravel?
- An EOF-on-worker-start failure usually means the worker process could not bootstrap, most often because the sockets PHP extension is missing, the required SDK package is absent, or server.command in .rr.yaml points to the wrong entry point. Bake the sockets extension into your image and keep a CI boot smoke test that starts RoadRunner and performs a real request. Verify that the Octane and SDK packages match the installed RoadRunner binary major.
- Do RoadRunner queue and KV plugins replace Laravel's queue drivers?
- No. RoadRunner queue features such as the NSQ driver, named job worker pools and job outcome metrics are RoadRunner plugin capabilities, not Laravel queue drivers. They do not become drop-in Laravel features simply because they exist in the server. If you need Laravel queue integration, evaluate the specific driver or bridge rather than assuming the plugin covers it.
- What alternatives to RoadRunner should I consider for Laravel?
- FrankenPHP and Swoole are the main alternatives, and FrankenPHP is generally the lower-ceremony option if you only need HTTP serving. RoadRunner remains compelling when you want its broader plugin surface for queues, KV, gRPC, Temporal or observability. Weigh governance, upgrade cadence and the Go toolchain requirement before committing, since custom builds or TCP support now require you to own the Go build.
Weaver
How can I help you explore Laravel packages today?