Roadrunner Bridge Laravel Package

Getting Started

1. Pin the package deliberately: composer require spiral/roadrunner-bridge:^4.0 for new apps. If you are coming from v3.6.0, budget the upgrade as a major: the v4 changelog is dominated by BC-sensitive work — Make implementations internal, Remove deprecations, logger handler changes, and interceptor argument normalization.
2. Install and pin the RoadRunner binary: Download the matching release from RoadRunner’s GitHub releases and put it in $PATH. Pin the binary version in your Dockerfile/CI image alongside the bridge version — several v4 changes (log normalization, EXIT handling, interceptor args) couple bridge behaviour to the server protocol.
3. Bootstrap via the documented entrypoint: Use the bridge’s documented entrypoint or wire its HttpKernel through custom routing. In v4 the implementation classes are explicitly internal, so code against the documented public contracts only — no extending or type-hinting concrete bridge classes.
4. First run: Start with ./rr serve -d. Immediately after upgrading, smoke-test four things the release touched: worker shutdown/EXIT behaviour, log output (levels, bubbling, escaping), TCP/Centrifugo interceptor payloads, and anything that touched deprecations in v3.

Implementation Patterns

• Long-lived request lifecycle: Replace PHP-FPM per-request bootstrapping with persistent workers. The Laravel container survives across requests; only reinitialize on config changes or explicit worker reload.
• Custom workers: Define queue consumers and event workers against documented public contracts. With implementations now internal in v4, treat the bridge’s concrete classes as off-limits and build on interfaces/bootstrappers instead.
• Runtime config via .rr.yaml: Keep RoadRunner config adjacent to .env. Example shape (verify keys against your pinned RoadRunner version):

  server:
    command: "php public/index.php"
  http:
    address: 0.0.0.0:8080
    pool:
      num_workers: 4
      max_jobs: 0
  logs:
    level: debug
    output: stderr
  

• Middleware integration: Laravel middleware still runs per request while service bindings persist. Put per-request cleanup in terminators/shutdown listeners, never in service constructors — a constructor that resets state runs once per worker, not once per request.
• Hot reload dev workflow: Run debug mode with file watchers so workers restart on changes. v4 fixes EXIT command handling, so previously “stuck” workers may now actually exit — re-verify your watch loop doesn’t thrash.
• Logging integration: v4 is a logger-heavy release: Alert and Emergency levels are fixed, log level and bubble behaviour changed, slashes/unicode are no longer escaped, and log output was normalized. If you ship RoadRunner logs to ELK/Datadog/Loki with a parser keyed on exact JSON/text, re-baseline the parser against real v4 output.
• TCP/Centrifugo interceptors: v4 normalizes interceptor arguments for TCP and Centrifugo. Update custom interceptors and broadcasting integrations, then test publish/subscribe round-trips end to end — not just worker boot.
• Upgrade-from-v3 grep list: Audit for direct imports of bridge concrete classes, deprecated methods and config keys, custom bootstrappers, custom logger handlers, and interceptor implementations. Each maps to one of the v4 PRs and is where breaks will surface.

Gotchas and Tips

• State awareness is critical: Persistent workers retain DB connections, static state, container singletons, and caches. Reset connections, clear request-scoped state, and close sockets in terminate callbacks or shutdown listeners.
• v4 upgrade audit: “Make implementations internal” plus “Remove deprecations” are the two highest-risk changes. Anything you previously extended, type-hinted, or instantiated from the bridge may now be internal or gone. Migrate to public contracts before touching anything else.
• Logger behaviour changed in several directions: Alert/Emergency mapping was fixed, level/bubble semantics changed, output was normalized, and escaping of slashes/unicode was removed. Re-check both the content and shape of logs; a passing app can still break a log pipeline. Confirm logs.level and logs.output are what you intend.
• EXIT/workflow lifecycle: v4 fixes EXIT command handling. Re-test graceful shutdown, worker restarts, and terminator cleanup — especially with max_jobs set or custom worker loops, where a previously silent no-op exit can now actually terminate the worker.
• .env overrides: RoadRunner does not read .env at runtime unless you explicitly trigger it. Bake critical values into .rr.yaml or pass them as environment flags at start.
• Debugging: Set RoadRunner logging to stderr at debug level. Remember dd()/dump() inside a worker goes to RoadRunner logs, not the CLI — a common “my dump vanished” moment.
• Extension points: Prefer documented public contracts and bootstrappers. After v4, do not extend implementation classes unless the docs explicitly name them as extension points.
• Deployment tip: Pre-warm Laravel caches (config:cache, route:cache, view:cache) before starting RoadRunner; persistent workers cannot meaningfully recompile caches at runtime.
• Memory leaks: Monitor per-worker RSS and consider max_jobs > 0 for long-lived ORM/Doctrine connections. Recycle workers periodically in production rather than waiting for OOM.
• Pin both halves: Bridge v4.x and the RoadRunner binary are co-dependent. A floating binary tag in CI is the fastest way to reproduce a “works locally” interceptor or log-format failure.