Roadrunner Laravel Package

## Getting Started

### Minimal Setup
1. **Installation**:
   ```bash
   composer require spiral/roadrunner-cli
   ./vendor/bin/rr get-binary

Ensure PHP extensions php-curl, php-zip, and php-sockets are enabled.

2. Configure .rr.yaml:

   version: '3'
   server:
     command: "php worker.php"
   http:
     address: "0.0.0.0:8080"
   

3. Create a Worker (worker.php):

   <?php
   use Spiral\RoadRunner;
   use Nyholm\Psr7;
   
   $worker = RoadRunner\Worker::create();
   $psrFactory = new Psr7\Factory\Psr17Factory();
   
   $httpWorker = new RoadRunner\Http\PSR7Worker($worker, $psrFactory, $psrFactory, $psrFactory);
   
   while ($req = $httpWorker->waitRequest()) {
       $rsp = new Psr7\Response();
       $rsp->getBody()->write('Hello RoadRunner!');
       $httpWorker->respond($rsp);
   }
   

4. Run:

   ./rr serve -c .rr.yaml
   

First Use Case: Replace Nginx + FPM

• Why? RoadRunner handles HTTP/2/3, gzip, and middleware (e.g., Prometheus metrics) natively.
• Example: Replace nginx + php-fpm with RoadRunner’s HTTP plugin for Laravel/Symfony apps.

Implementation Patterns

1. HTTP Server Integration

• Laravel/Symfony: Use RoadRunner\Http\PSR7Worker with PSR-7 factories (e.g., nyholm/psr7).

  $app = require __DIR__.'/bootstrap/app.php';
  $worker = new RoadRunner\Http\PSR7Worker(
      RoadRunner\Worker::create(),
      $app->getPsr7Factory(),
      $app->getPsr7Factory(),
      $app->getPsr7Factory()
  );
  

• Middleware: Leverage RoadRunner’s built-in middleware (e.g., gzip, headers) in .rr.yaml:

  http:
    middleware: [gzip, headers]
  

2. Queue Workers

• Jobs Plugin: Define a queue worker in worker.php:

  $jobsWorker = new RoadRunner\Jobs\JobsWorker($worker);
  while ($job = $jobsWorker->wait()) {
      $result = dispatch($job->getPayload());
      $jobsWorker->complete($job, $result);
  }
  

• Config: Enable in .rr.yaml:

  jobs:
    pool:
      num_workers: 4
    queues: ["default"]
  

3. gRPC Services

• Protobuf: Use RoadRunner\Grpc\GrpcWorker with generated protobuf classes.

  $grpcWorker = new RoadRunner\Grpc\GrpcWorker($worker, __DIR__.'/proto');
  $grpcWorker->run();
  

• Config: Define in .rr.yaml:

  grpc:
    proto: "proto/**/*.proto"
  

4. OpenTelemetry

• Instrumentation: Add OTEL middleware to .rr.yaml:

  http:
    middleware: [otel]
  

• Exporters: Configure in otel.yaml (e.g., Jaeger, Prometheus).

5. Workflows (Temporal)

• Integration: Use RoadRunner\Temporal\TemporalWorker for workflows:

  $temporalWorker = new RoadRunner\Temporal\TemporalWorker($worker);
  $temporalWorker->run();
  

• Config: Enable in .rr.yaml:

  temporal:
    connection: "temporal://localhost:7233"
  

6. Service Management

• Systemd-like: Use RoadRunner’s process manager for auto-restarts:

  server:
    max_restarts: 5
    restart_delay: 10s
  

Gotchas and Tips

Common Pitfalls

1. EOF Errors:

   • Cause: Missing php-sockets or incorrect worker command.
   • Fix: Verify php --modules | grep sockets and ensure server.command in .rr.yaml matches your worker script.

2. Configuration Reloads:

   • Issue: Changes to .rr.yaml aren’t reflected without restart.
   • Fix: Use SIGUSR2 (Unix) or rr reload (v2025.1.5+):

     kill -USR2 $(pgrep rr)
     

3. gRPC Protobuf Paths:

   • Gotcha: Glob patterns (**, {a,b}) require Go 1.25+.
   • Fix: Update Go and ensure paths in .rr.yaml are correct:

     grpc:
       proto: "proto/**/*.proto"
     

4. KV Plugin Null Pointers:

   • Bug: KV plugin crashes if no Redis driver is configured (v2025.1.0).
   • Fix: Upgrade to v2025.1.1 or explicitly define a driver:

     kv:
       redis:
         dsn: "redis://localhost"
     

5. Green Tea GC:

   • Issue: Disabled by default in v2025.1.4 due to bugs.
   • Fix: Re-enable via environment variable:

     RR_GOGC=100 ./rr serve
     

Debugging Tips

1. Logs:

   • Set logs.level: debug in .rr.yaml for verbose output.
   • Stream logs with:

     ./rr logs -c .rr.yaml
     

2. Metrics:

   • Expose Prometheus metrics via middleware:

     http:
       middleware: [prometheus]
     

   • Access at http://localhost:8080/metrics.

3. Worker Isolation:

   • Use separate processes for HTTP/Jobs/gRPC to avoid resource contention:

     server:
       command_all: ["php worker-http.php", "php worker-jobs.php"]
     

Extension Points

1. Custom Middleware:

   • Implement RoadRunner\Http\MiddlewareInterface and register in .rr.yaml:

     http:
       middleware: [custom_middleware]
     

2. Plugin Development:

   • Extend RoadRunner with Go plugins (e.g., custom KV drivers).
   • Example: RoadRunner Plugins Docs.

3. Docker Optimization:

   • Multi-stage builds to reduce image size:

     FROM ghcr.io/roadrunner-server/roadrunner:2025.X.X AS roadrunner
     FROM php:8.3-cli
     COPY --from=roadrunner /usr/bin/rr /usr/local/bin/rr
     

4. TLS Management:

   • Auto-generate certs with rr tls generate (v2025.1.0+):

     ./rr tls generate --cert=cert.pem --key=key.pem
     

   • Configure in .rr.yaml:

     http:
       tls:
         cert: "cert.pem"
         key: "key.pem"
     

Performance Tuning

1. Worker Pool:

   • Adjust jobs.pool.num_workers based on CPU cores (e.g., 4 for 4 cores).

2. HTTP Keep-Alive:

   • Enable in .rr.yaml:

     http:
       keep_alive: true
     

3. gRPC Compression:

   • Use protobuf extension for faster serialization:

     docker-php-ext-install protobuf
     

4. Early Hints (103):

   • Enable for HTTP/2:

     http:
       early_hints: true
     

Security

1. CVE Mitigations:

   • Always update RoadRunner (./rr update) to patch CVEs (e.g., gRPC, Go stdlib).
   • Example: v2025.1.12 fixed CVE-2026-33186 in gRPC.

2. TLS:

   • Enforce TLS in .rr.yaml:

     http:
       tls:
         cert: "cert.pem"
         key: "key.pem"
         min_version: "TLS12"
     

3. Proxy Headers:

   • Parse real IPs with proxy_ip_parser middleware:

     http:
       middleware: [proxy_ip_parser]
     

CI/CD

1. **