Weave Code
Roadrunner Laravel Package
spiral/roadrunner
High-performance PHP application server and process manager written in Go. RoadRunner replaces Nginx+FPM with long-running workers and a plugin system, offering HTTP(S)/2/3, FastCGI, PSR-7/17 support, and per-project extensibility.
🤯 High-performance PHP application server, process manager written in Go and powered with plugins
Frequently asked questions about Roadrunner
- How does RoadRunner compare to Laravel’s built-in `php artisan serve` or Nginx+FPM in terms of performance?
- RoadRunner outperforms `php artisan serve` significantly and often matches or exceeds Nginx+FPM in throughput, especially for I/O-bound workloads. Benchmarks show lower latency and higher request handling capacity due to its Go-based process management and HTTP/2/3 support. For Laravel APIs, it’s a drop-in replacement for FPM with better resource utilization.
- Can I use RoadRunner with Laravel 10+ without modifying existing middleware or controllers?
- Yes, RoadRunner is fully compatible with Laravel’s PSR-7 stack (via `nyholm/psr7` or its built-in adapter). Middleware like `VerifyCsrfToken` or `ShareErrorsFromSession` works unchanged, as does Laravel’s request/response handling. No code changes are needed for basic HTTP routes or middleware.
- How do I replace `php artisan queue:work` with RoadRunner’s job plugin for Laravel queues?
- RoadRunner’s job plugin replaces `queue:work` by configuring it in `.rr.yaml` to handle Laravel’s queue connections (Redis, database, etc.). It supports concurrency, retries, and batching out-of-the-box. Use the `jobs` section in `.rr.yaml` to define workers, and ensure your queue drivers are PSR-15 compliant or wrapped with adapters.
- Does RoadRunner support WebSockets or gRPC for real-time Laravel applications?
- Yes, RoadRunner includes plugins for WebSockets (via `websockets` plugin) and gRPC (via `grpc` plugin). For Laravel, you can use these to build real-time APIs or microservices. The gRPC plugin is particularly useful for high-performance RPC calls, while WebSockets work seamlessly with Laravel Echo or custom event broadcasting.
- What’s the minimal configuration needed to run RoadRunner with Laravel?
- The minimal setup requires a `.rr.yaml` file with an `http` server block, e.g., `http.address: 0.0.0.0:8080`. For Laravel, you’ll also need to install the `spiral/roadrunner-http` package and configure it to use Laravel’s PSR-7 middleware stack. Example: `server: spiral/roadrunner-http:http`. No `.env` changes are needed unless you want to bind dynamic values.
- How does RoadRunner handle sessions in Laravel, especially if I’m using file-based storage?
- RoadRunner is stateless by design, so file-based sessions won’t work directly. You must switch to Redis or Memcached for session storage, which Laravel already supports as a fallback. This is a best practice for scalability anyway, and RoadRunner’s performance benefits outweigh the minor migration effort.
- Can RoadRunner replace Nginx entirely, or do I still need it for TLS termination or static files?
- RoadRunner can handle HTTP/HTTPS traffic directly, but it’s often used behind Nginx for TLS termination, static file serving, or WebSocket upgrades. Nginx acts as a reverse proxy, offloading SSL and routing requests to RoadRunner on `localhost:8080`. This setup is common in production environments.
- Are there any known issues with RoadRunner’s Go dependency in production (e.g., crashes, memory leaks)?
- RoadRunner’s Go core is stable and widely used, with proactive CVE fixes. Memory leaks are rare due to Go’s garbage collection, but monitor worker processes with `rr trace` or Prometheus metrics. The project’s active maintenance (8.5K stars, MIT license) and Go 1.26+ compatibility reduce risks significantly.
- How do I debug issues when RoadRunner and Laravel logs aren’t correlating?
- Use OpenTelemetry for distributed tracing to correlate Laravel logs (Monolog) with RoadRunner’s structured JSON logs. Install the `laravel-otel` package and configure both systems to use the same trace IDs. RoadRunner’s `rr trace` command also helps inspect worker-level metrics and errors.
- What’s the effort to migrate from FPM to RoadRunner in a Laravel project with custom workers or cron jobs?
- Migrating FPM to RoadRunner is straightforward for HTTP routes but requires rewiring custom workers or cron jobs to use RoadRunner’s job plugin. Replace `worker.php` with a RoadRunner-compatible setup, and update cron entries to trigger RoadRunner’s job workers. The effort depends on your project’s complexity, but most Laravel apps see minimal changes.
Weaver
How can I help you explore Laravel packages today?