Roadrunner Bundle Laravel Package

Technical Evaluation

Architecture Fit

• High Performance Alignment: The bundle integrates RoadRunner, a high-performance PHP application server written in Go, with Symfony. This is a strong architectural fit for applications requiring low-latency, high-throughput processing (e.g., APIs, microservices, or event-driven workflows).
• Symfony Compatibility: Designed for Symfony 4.4+ (including Symfony 6.x), leveraging its DI container, HTTP stack, and middleware system. The bundle preserves Symfony’s kernel between requests (with configurable reboot strategies), optimizing memory usage while maintaining stateful services.
• Extensibility: Supports custom middlewares, kernel reboot strategies, metrics collection, gRPC, and KV caching, making it adaptable to complex use cases (e.g., real-time systems, hybrid HTTP/gRPC services).
• RoadRunner Ecosystem: Taps into RoadRunner’s plugins (e.g., roadrunner-grpc, roadrunner-kv), enabling advanced features like distributed task queues, gRPC, and shared memory caching without reinventing the wheel.

Integration Feasibility

• Seamless Symfony Integration: The bundle replaces Symfony’s built-in web server (e.g., php -S) with RoadRunner, requiring minimal changes to existing codebases. Key integrations (Doctrine, Sentry, Blackfire, Sessions) are automatically enabled if their bundles are present.
• PSR-15 Middleware Support: While the bundle deprecated PSR-15 middleware in favor of Symfony’s native middleware system, it still supports custom middleware via MiddlewareInterface, ensuring flexibility for request/response manipulation.
• Configuration Override: RoadRunner’s .rr.yaml and Symfony’s baldinof_road_runner.yaml are merged, allowing fine-grained control over server behavior (e.g., worker pools, timeouts, gRPC ports).
• Dev/Prod Parity: Includes dev-mode reloading (via .rr.dev.yaml) and production-optimized configurations, reducing friction between environments.

Technical Risk

• Kernel Reboot Complexity: The bundle’s kernel reboot strategies (e.g., on_exception, max_jobs, memory) introduce state management trade-offs:
  • Pros: Prevents memory leaks, resets stateful services (e.g., Doctrine connections).
  • Cons: May increase cold-start latency if rebooting frequently. Requires careful tuning of allowed_exceptions and max_jobs thresholds.
• RoadRunner Dependency: Relies on Go binaries (rr), which must be installed and managed (e.g., via composer require spiral/roadrunner-cli). Docker deployments (as shown in the README) mitigate this but add complexity.
• Middleware Performance: Middlewares run outside Symfony’s Kernel::handle(), which could lead to duplicated logic if not managed carefully. The warning about performance overhead for heavy middleware initialization is valid.
• Doctrine Integration: While the bundle handles connection reconnection for Doctrine ORM/MongoDB, long-running transactions or stateful repositories may still require manual cleanup (e.g., implementing ResetInterface).
• gRPC/KV Plugins: Requires additional dependencies (spiral/roadrunner-grpc, spiral/roadrunner-kv) and configuration, increasing operational surface area.

Key Questions

1. Performance vs. Statefulness:

   • How will the kernel reboot strategy impact our application’s latency and throughput? Should we use always, on_exception, or a hybrid approach?
   • Are there stateful services (e.g., caches, connection pools) that require ResetInterface or manual cleanup?

2. Deployment Complexity:

   • How will we manage RoadRunner binaries in production (e.g., CI/CD, containerization)? Will we use the provided Dockerfile or a custom setup?
   • What monitoring is needed for RoadRunner metrics (e.g., Prometheus, custom dashboards)?

3. Middleware Strategy:

   • Should we avoid heavy middleware or refactor existing PSR-15 middlewares to Symfony’s native format?
   • How will we test middleware behavior outside Kernel::handle()?

4. Error Handling:

   • What exceptions should be allowed to avoid unnecessary kernel reboots? Are there domain-specific exceptions we should whitelist?
   • How will we debug issues when the kernel reboots silently (e.g., memory leaks)?

5. Advanced Features:

   • Do we need gRPC or KV caching? If so, what are the trade-offs (e.g., additional dependencies, configuration overhead)?
   • How will we integrate metrics with our existing observability stack (e.g., Prometheus, Datadog)?

Integration Approach

Stack Fit

• Symfony-Centric: The bundle is optimized for Symfony, leveraging its DI container, HTTP stack, and middleware system. It replaces Symfony’s built-in server with RoadRunner, making it ideal for:
  • APIs (REST/gRPC).
  • Microservices with high concurrency needs.
  • Event-driven architectures (e.g., using RoadRunner’s task workers).
• RoadRunner Ecosystem: Enables Go-powered performance while keeping PHP/Symfony logic intact. Key features:
  • Worker pools: Horizontal scaling via multiple PHP workers.
  • gRPC support: For polyglot services (e.g., PHP + Go + Java).
  • KV caching: Low-latency shared memory caching.
  • Metrics: Built-in Prometheus integration.
• DevOps Alignment: Works well with Docker, Kubernetes, and serverless (e.g., AWS Fargate) due to its stateless design (when configured properly).

Migration Path

1. Assessment Phase:

   • Audit current Symfony server setup (e.g., php -S, Nginx/PHP-FPM).
   • Identify stateful services (e.g., Doctrine, caches) that may need ResetInterface.
   • Evaluate middleware dependencies (PSR-15 vs. Symfony native).

2. Pilot Integration:

   • Install the bundle in a staging environment:

     composer require baldinof/roadrunner-bundle spiral/roadrunner-cli
     

   • Configure .rr.yaml and baldinof_road_runner.yaml with default settings.
   • Test with bin/rr serve -c .rr.dev.yaml in dev mode.

3. Incremental Rollout:

   • Phase 1: Replace the dev server with RoadRunner (no kernel reboots initially).
   • Phase 2: Enable kernel reboots (on_exception) and monitor memory usage.
   • Phase 3: Introduce advanced features (gRPC, KV caching, metrics) as needed.

4. Production Hardening:

   • Containerize RoadRunner (e.g., using the provided Dockerfile).
   • Tune worker pools in .rr.yaml (e.g., worker_pool_size).
   • Integrate metrics with Prometheus/Grafana.
   • Implement health checks (e.g., /health endpoint).

Compatibility

• Symfony Versions: Supports 4.4+ to 6.x, with forward compatibility for Symfony 7.
• Doctrine: Works with ORM and MongoDB, with automatic connection handling.
• Sentry/Blackfire: Automatically integrated if their bundles are installed.
• PSR Standards: Uses PSR-7 (Symfony’s bridge) and PSR-15 (deprecated but supported).
• RoadRunner Plugins: Compatible with official plugins (e.g., roadrunner-grpc, roadrunner-kv).

Sequencing

1. Core Integration:

   • Replace Symfony’s server with RoadRunner.
   • Configure kernel reboots (on_exception).
   • Test basic HTTP routes.

2. Performance Tuning:

   • Adjust worker pool size in .rr.yaml.
   • Monitor memory usage and tweak memory_threshold_mb.

3. Advanced Features:

   • Add gRPC if needed (requires spiral/roadrunner-grpc).
   • Enable KV caching for shared state.
   • Set up Prometheus metrics.

4. Observability:

   • Integrate Sentry/Blackfire for error tracking.
   • Add custom metrics (e.g., business KPIs).

5. CI/CD:

   • Automate RoadRunner binary installation in pipelines.
   • Test kernel reboot strategies in staging.

Operational Impact

Maintenance

• Bundle Updates: The package is actively maintained (last release: 2026-05-27), with a clear changelog and MIT license. Depend