Roadrunner Laravel Package

Technical Evaluation

Architecture Fit

RoadRunner is a high-performance PHP application server that replaces traditional Nginx+FPM setups, offering lower latency, better resource utilization, and plugin-based extensibility. It aligns well with modern Laravel architectures by:

• Replacing FPM: Eliminates the need for a separate PHP-FPM pool, reducing overhead.
• PSR-7/PSR-15 Compliance: Integrates seamlessly with Laravel’s HTTP middleware stack (e.g., Illuminate\Http\Middleware).
• Plugin Ecosystem: Supports HTTP/2/3, gRPC, queues (RabbitMQ, Kafka, SQS), OpenTelemetry, and workflow engines (Temporal), enabling microservices, event-driven, and observability-first architectures.
• Stateless Workers: Enables horizontal scaling without shared memory bottlenecks (unlike FPM).

Key Laravel Synergies:

• Lumen/HTTP APIs: RoadRunner’s HTTP server is a drop-in replacement for Laravel’s built-in server.
• Queues: Native support for Laravel’s queue workers (via spiral/roadrunner-jobs plugin).
• gRPC: Enables high-performance RPC for Laravel services (e.g., real-time APIs, microservices).
• Observability: OpenTelemetry integration for distributed tracing (complements Laravel Scout, Horizon, etc.).

Integration Feasibility

Laravel-Specific Considerations:

• Service Providers: RoadRunner workers are stateless; Laravel’s bind()/singleton() may need adjustments for shared state.
• Middleware: PSR-15 middleware (e.g., App\Http\Middleware\Authenticate) works natively.
• Events/Listeners: Requires explicit integration (e.g., via spiral/roadrunner-events plugin).
• Artisan Commands: RoadRunner does not replace Artisan; CLI tasks must run separately.

Technical Risk

Critical Questions for TPM:

1. Statefulness: How will Laravel’s session/cache (e.g., file, database) work in a stateless RoadRunner environment?
2. Queue Workers: Will existing Laravel queue jobs (e.g., Illuminate\Queue\Jobs\Job) work out-of-the-box with RoadRunner’s plugins?
3. Middleware Order: How will Laravel’s middleware groups (e.g., web, api) map to RoadRunner’s middleware stack?
4. Artisan Integration: Can RoadRunner trigger Artisan commands (e.g., schedule:run) without blocking HTTP workers?
5. Observability: How will Laravel’s logging (Monolog) integrate with RoadRunner’s OpenTelemetry metrics?
6. Deployment: How will rolling updates work for RoadRunner workers (e.g., zero-downtime deploys)?
7. Cost: Does RoadRunner’s Go overhead justify the performance gains over FPM for our workload?

Integration Approach

Stack Fit

RoadRunner is optimized for Laravel when paired with:

• PHP 8.2+: Required for performance and compatibility (e.g., JIT, fiber support).
• PSR-7/PSR-15: Laravel’s HTTP layer (e.g., nyholm/psr7, psr/http-message) is fully compatible.
• Async PHP: Leverages spiral/roadrunner-http for non-blocking I/O (e.g., database calls).
• Container Orchestration: Best suited for Kubernetes/Docker (native support for SIGUSR2 graceful restarts).
• Observability Stack: Integrates with OpenTelemetry, Prometheus, and Jaeger for distributed tracing.

Anti-Patterns:

• Monolithic Apps: RoadRunner shines in microservices or high-concurrency scenarios; not ideal for simple CRUD apps.
• Shared Memory: Avoid in-memory caching (e.g., array cache) unless externalized (Redis).
• Blocking I/O: Heavy synchronous operations (e.g., file_get_contents) will degrade performance.

Migration Path

Example .rr.yaml for Laravel:

version: '3'
server:
  command: "php artisan roadrunner:work"
http:
  address: "0.0.0.0:8080"
  middleware: ["static", "otel", "gzip"]
  pool:
    num_workers: auto
    max_jobs: 100
    allocate_timeout: 60s
    destroy_timeout: 60s
jobs:
  queue: "redis"
  pool:
    num_workers: 4
    max_jobs: 100
otel:
  service_name: "laravel-app"
  exporter: "otlp"
  otlp:
    endpoint: "http://jaeger:4317"

Compatibility