Roadrunner Bundle Laravel Package

Technical Evaluation

Architecture Fit

• High Performance Alignment: The bundle leverages RoadRunner, a high-performance PHP application server, which aligns well with Symfony’s architecture for handling concurrent requests efficiently. RoadRunner’s event-loop model (via Goridge) is particularly suited for I/O-bound applications (e.g., APIs, microservices).
• Symfony Compatibility: Designed as a Symfony Bundle, it integrates seamlessly with Symfony’s DI container, HTTP kernel, and middleware stack. Supports PSR-15 middleware, PSR-7 HTTP messages, and Symfony’s ResetInterface for stateful services.
• Modularity: Offers optional integrations (Sentry, Doctrine, Blackfire, Metrics) that can be enabled/disabled via configuration, reducing bloat in non-relevant use cases.

Integration Feasibility

• Low Friction: Installation is straightforward (Composer + bundle registration), and the bundle handles RoadRunner binary acquisition automatically. Minimal manual configuration is required for basic usage.
• Symfony Ecosystem Fit: Works with Symfony’s core components (e.g., HttpKernel, DependencyInjection) and bundles (e.g., Sentry, Doctrine). Requires symfony/psr-http-message-bridge for PSR-17 factories, which is a common dependency.
• DevOps Readiness: Includes Docker support and dev-mode configurations (auto-reload), easing CI/CD and local development.

Technical Risk

• Kernel Reboot Behavior: Symfony’s kernel is preserved between requests by default, which can lead to memory leaks or state corruption if services aren’t stateless. The bundle mitigates this with configurable reboot strategies (always, on_exception), but misconfiguration could cause instability.
• Database Connection Handling: RoadRunner’s stateless nature conflicts with persistent DB connections. The bundle provides a workaround via symfony/proxy-manager-bridge for Doctrine, but other ORMs (e.g., Eloquent) may require custom solutions.
• Middleware Execution Context: Middlewares run outside Symfony’s Kernel::handle(), which could break assumptions in custom middleware (e.g., dependency injection, kernel access). The bundle documents this but requires careful testing.
• Metrics Dependency: Enabling metrics requires additional Go-side configuration (e.g., RPC socket setup) and may introduce latency if not tuned properly.

Key Questions

1. Performance vs. Stability Tradeoff:

   • How will the team balance RoadRunner’s performance gains against Symfony’s default request lifecycle (e.g., kernel reboot strategies)?
   • Are there stateful services that could break under on_exception reboot mode?

2. Database Integration:

   • For non-Doctrine ORMs (e.g., Eloquent), how will persistent connections be managed? Will custom middleware or connection handlers be needed?

3. Middleware Compatibility:

   • Does the application rely on middleware that assumes Symfony’s kernel context (e.g., accessing RequestStack)? If so, how will these be adapted?

4. Observability:

   • How will metrics (e.g., custom counters) be monitored? Are tools like Prometheus/Grafana already integrated?
   • For Sentry, how will the new scope-clearing fix (v1.3.2) impact existing error tracking?

5. Deployment Complexity:

   • What’s the rollout strategy for RoadRunner? Will it replace existing PHP-FPM, or run alongside it (e.g., for specific routes)?
   • How will the Go binary (rr) be managed in production (updates, permissions, logging)?

6. Dev Experience:

   • How will the dev-mode auto-reload interact with Symfony’s built-in dev tools (e.g., VarDumper, Profiler)?
   • Are there plans to integrate with Symfony’s UX (e.g., error pages, debug toolbar)?

Integration Approach

Stack Fit

• Target Environments:
  • APIs/Microservices: Ideal for high-concurrency HTTP APIs where RoadRunner’s event-loop model excels.
  • CLI Workers: RoadRunner’s RPC capabilities enable async task queues (e.g., via rr worker), but this bundle focuses on HTTP.
  • Legacy Symfony Apps: Can incrementally adopt RoadRunner for specific routes (e.g., via middleware routing) without full migration.
• Symfony Version Support: Compatible with Symfony 4.4+ and 5.x, with explicit support for symfony/psr-http-message-bridge v2.
• Alternatives Considered:
  • Swoole/SwooleBundle: Higher performance but tighter coupling to PHP extensions.
  • ReactPHP: More manual setup but finer control over async logic.
  • Native PHP-FPM: Lower overhead but no event-loop benefits.

Migration Path

1. Assessment Phase:
   • Audit stateful services (e.g., caches, DB connections) and middleware dependencies.
   • Benchmark current PHP-FPM vs. RoadRunner (e.g., ab, k6) to validate performance gains.
2. Staged Rollout:
   • Phase 1: Deploy RoadRunner alongside PHP-FPM for non-critical routes (e.g., /api/v2).
     • Use middleware to route traffic (e.g., if ($request->getPathInfo() === '/api/v2') { ... }).
   • Phase 2: Migrate critical routes, starting with stateless services.
   • Phase 3: Replace PHP-FPM entirely, adjusting kernel reboot strategies and connection handling.
3. Configuration Migration:
   • Replace php.ini/pool.d/ configs with .rr.yaml (e.g., worker pools, timeouts).
   • Update Symfony’s framework.session config for database-backed sessions (if used).
4. Dependency Updates:
   • Ensure symfony/psr-http-message-bridge is v2.x.
   • Add symfony/proxy-manager-bridge for Doctrine if not already present.

Compatibility

• Symfony Bundles:
  • Sentry: Works out-of-the-box with scope clearing (fixed in v1.3.2).
  • Doctrine: Requires proxy-manager-bridge for ORM; MongoDB ODM has built-in support.
  • Blackfire: Supported but may need PSR-7 adapter tweaks.
  • Custom Bundles: May need adjustments if they rely on Symfony’s kernel context (e.g., ContainerAware services).
• PSR Standards:
  • Fully compliant with PSR-15 (middleware), PSR-7 (HTTP messages), and PSR-17 (factories).
  • Falls back to php-http/discovery if no PSR-17 factories are found.
• RoadRunner Features:
  • Supports HTTP, RPC, and metrics out of the box.
  • Dev-mode auto-reload requires .rr.dev.yaml (not enabled by default).

Sequencing

1. Prerequisites:
   • Upgrade Symfony to 4.4+/5.x if not already.
   • Install symfony/psr-http-message-bridge (v2.x).
   • For Doctrine: Add symfony/proxy-manager-bridge.
2. Bundle Installation:

   composer require andrey_mireichyk/roadrunner-bundle
   

   Register the bundle in config/bundles.php:

   Baldinof\RoadRunnerBundle\BaldinofRoadRunnerBundle::class => ['all' => true],
   

3. Configuration:
   • Copy default configs: cp vendor/andrey_mireichyk/roadrunner-bundle/.rr.* ..
   • Configure .rr.yaml (e.g., worker pools, timeouts) and config/packages/baldinof_road_runner.yaml (e.g., kernel reboot, metrics).
4. Testing:
   • Start RoadRunner in dev mode: bin/rr serve -c .rr.dev.yaml.
   • Test with symfony/var-dumper via bin/console server:dump.
5. Production Deployment:
   • Build RoadRunner binary: vendor/bin/rr get --location bin/.
   • Deploy with Docker or standalone (see Dockerfile in README).
   • Warm up cache: bin/console cache:warmup.

Operational Impact

Maintenance

• Bundle Updates:
  • Monitor for breaking changes (e.g., kernel reboot strategy deprecations in v1.3.0).
  • Test upgrades incrementally, especially for Doctrine/Session integrations.
• RoadRunner Binary:
  • Manage Go binary updates (e.g., via rr get or pinned versions).
  • Monitor for Go/PHP version compatibility (e.g., PHP 8.x support).
• Configuration Drift:
  • Centralize .rr.yaml and baldinof_road_runner.yaml in version control.
  • Use tools like rr dump-config to validate configs post-deployment.

Support

• Debugging:
  • RoadRunner logs are separate from Symfony’s (check rr serve output).
  • Use bin/console debug:container to inspect DI issues.
  • Metrics/RPC can expose runtime stats (e.g., worker health, request latency).
• Common Issues:
  • Kernel Reboot: Logs may show Kernel rebooted; adjust allowed_exceptions as needed.