Roadrunner Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Bundle:

   composer require andrey_mireichyk/roadrunner-bundle
   

   If not using Symfony Flex, manually register the bundle in config/bundles.php:

   return [
       // ...
       Baldinof\RoadRunnerBundle\BaldinofRoadRunnerBundle::class => ['all' => true],
   ];
   

2. Fetch RoadRunner Binary:

   vendor/bin/rr get --location bin/
   

3. Configure RoadRunner: Copy default config files:

   cp vendor/andrey_mireichyk/roadrunner-bundle/.rr.* .
   

4. Start RoadRunner:

   bin/rr serve
   

   Access your app at http://localhost:8080.

First Use Case: Replace Symfony’s Built-in Server

Replace Symfony’s php bin/console server:run with RoadRunner for production-like performance during development:

bin/rr serve -c .rr.dev.yaml  # Use dev config for auto-reload

Implementation Patterns

Workflow: Integrating RoadRunner with Symfony

1. Kernel Reboot Strategy: Configure kernel reboot behavior in config/packages/baldinof_road_runner.yaml:

   baldinof_road_runner:
       kernel_reboot:
           strategy: on_exception  # Default; reboot only on uncaught exceptions
           allowed_exceptions:
               - Symfony\Component\HttpKernel\Exception\HttpExceptionInterface
   

   • Use strategy: always for stateless services (e.g., APIs).
   • Implement Symfony\Contracts\Service\ResetInterface for stateful services.

2. Middleware Integration: Add custom middleware (PSR-15 or IteratorMiddlewareInterface) in config/packages/baldinof_road_runner.yaml:

   baldinof_road_runner:
       middlewares:
           - App\Middleware\LoggingMiddleware
           - App\Middleware\CachingMiddleware
   

   Note: Middlewares run outside Kernel::handle(). Use IteratorMiddlewareInterface for post-response logic (e.g., logging).

3. Metrics Collection: Enable metrics in config/packages/baldinof_road_runner.yaml:

   baldinof_road_runner:
       metrics_enabled: true
   

   Configure .rr.yaml:

   metrics:
       address: localhost:2112
       collect:
           app_requests_total:
               type: counter
               help: "Total HTTP requests."
   

   Inject Spiral\RoadRunner\MetricsInterface in controllers:

   public function index(MetricsInterface $metrics): Response {
       $metrics->add('app_requests_total', 1);
       return new Response('OK');
   }
   

4. Database Connection Handling: For Doctrine, install symfony/proxy-manager-bridge to handle reconnections:

   composer require symfony/proxy-manager-bridge
   

   Configure session storage in the database using shapecode/doctrine-session-handler-bundle:

   composer require shapecode/doctrine-session-handler-bundle
   

Integration Tips

• Sentry Integration: Automatically configures request context if getsentry/sentry-symfony is installed.
• Session Support: Adds session cookies to PSR responses if framework.sessions.enabled is true.
• Doctrine MongoDB: Calls clear() on managers post-request to avoid connection leaks.
• Blackfire: Works out-of-the-box with blackfire/php-sdk. Ensure nyholm/psr7 is installed if using sensio/framework-extra-bundle.

Gotchas and Tips

Pitfalls

1. Kernel State Persistence:

   • The Symfony kernel persists between requests by default. Uncaught exceptions trigger a reboot.
   • Fix: Use strategy: always or whitelist exceptions in allowed_exceptions.

2. Middleware Initialization:

   • Middleware stacks are resolved once at worker startup. Heavy initialization (e.g., DB connections) can cause delays.
   • Workaround: Lazy-load dependencies in middleware constructors.

3. Metrics Injection:

   • If metrics_enabled: false, MetricsInterface injects a NullMetrics instance. Check config before recording:

   if ($metrics instanceof Spiral\RoadRunner\NullMetrics) {
       return $response;
   }
   

4. Dev Mode Quirks:

   • Symfony’s VarDumper dumps won’t appear in HTTP responses. Use bin/console server:dump or the profiler.
   • Auto-reload requires .rr.dev.yaml and bin/rr serve -c .rr.dev.yaml.

5. PSR-7 Factories:

   • If no PSR-17 factories are found, the bundle falls back to php-http/discovery. Ensure nyholm/psr7 or symfony/psr-http-message-bridge is installed.

6. TCP Relay Configuration:

   • Override Spiral\Goridge\RelayInterface in services.yaml for custom transports (e.g., TCP sockets):

   services:
       Spiral\Goridge\RelayInterface:
           class: Spiral\Goridge\SocketRelay
           arguments: ['localhost', 7000]
   

   Update .rr.yaml:

   http:
       workers:
           relay: "tcp://localhost:7000"
   

Debugging Tips

1. Worker Logs: Check RoadRunner logs for errors:

   bin/rr logs
   

   Or tail the log file (default: var/log/roadrunner.log).

2. Connection Issues: Doctrine reconnection errors may crash workers. Use symfony/proxy-manager-bridge and configure kernel_reboot to handle failures gracefully.

3. Middleware Debugging: Log middleware execution in IteratorMiddlewareInterface:

   public function __invoke(ServerRequestInterface $request, callable $next) {
       error_log('Middleware executed');
       $response = $next($request);
       error_log('Response sent');
       return $response;
   }
   

4. Metrics Verification: Validate metrics collection with:

   curl http://localhost:2112/metrics
   

   Or use Prometheus tools like promtool.

Extension Points

1. Custom Kernel Reboot Logic: Extend Baldinof\RoadRunnerBundle\Worker\Worker (internal) or implement Symfony\Contracts\Service\ResetInterface for stateful services.

2. Relay Transport: Replace Spiral\Goridge\RelayInterface for custom transports (e.g., gRPC, WebSockets).

3. Post-Response Hooks: Use IteratorMiddlewareInterface for logic after response sending (e.g., analytics, cleanup).

4. Metrics Customization: Extend Spiral\RoadRunner\MetricsInterface or add new metric types in .rr.yaml:

   metrics:
       collect:
           custom_metric:
               type: gauge
               help: "Custom application metric."