Roadrunner Cli Laravel Package

Technical Evaluation

Architecture fit: Still the right package for Laravel/PHP teams running RoadRunner, but the fit has changed shape. roadrunner-php/cli 3.0.0 is no longer a maintenance-level bump — it is a platform migration package that targets RoadRunner server v3 exclusively. The dependency chain is now Laravel app → CLI 3.x → RoadRunner 3.x → rewritten .rr.yaml. Teams on RoadRunner 2.x cannot adopt this without migrating the server, which makes the CLI upgrade a coupled infrastructure project rather than a Composer bump.

Integration feasibility: Feasible but conditional. The public surface (Symfony console commands, config generation) is stable in intent; everything under Command, Configuration, Downloader, Environment, Archive, and Repository has moved to Internal\* or been removed. Any Laravel app with custom commands extending Spiral\RoadRunner\Console\Command, custom OptionInterface implementations, or code calling Environment\Enum / Environment\*\Factory will break at autoload. Most Laravel apps use this package as a black box (vendor/bin/rr get-binary, config generation), so the blast radius is smaller than the changelog suggests — but that must be confirmed, not assumed.

Technical risks:

• Hard RoadRunner 3 coupling: the wildcard version filter now installs RoadRunner 3.0+, and generated configuration is RR3-only. A wildcard get-binary in CI will silently pull an RR3 binary under an RR2 runtime.
• Removed plugins: tcp, websockets, broadcast, and reload are gone because RR3 does not ship them. Any .rr.yaml using them — or Laravel code relying on the reload/broadcast semantics — must be re-architected, not just edited.
• PHP 8.2 minimum: Laravel 9.x and early 10.x deployments on PHP 8.0/8.1 are excluded. This creates a three-way version constraint (PHP, Laravel, RoadRunner) that must be satisfied simultaneously.
• Symfony floor: symfony/console and symfony/http-client 6.4+ are now required. The prior assessment's concern about Symfony 8.0 behavior is largely resolved, but the floor is a real constraint for pinned Laravel 9 apps.
• GitHub Enterprise auth change: RR_GITHUB_API_URL must be exactly https://api.github.com or end with /api/v3, and the token moves from GITHUB_TOKEN to DLOAD_TOKEN_<HOST> (e.g. DLOAD_TOKEN_GHE_EXAMPLE_COM). GitHub.com users are unaffected; GHES users must rotate CI secrets or binary downloads fail.
• Internal namespace volatility: declaring Command, Configuration, Downloader, Environment internal removes any SemVer guarantee for those classes going forward. Extension points should be treated as unsupported.

Key questions:

1. Is production RoadRunner v2 or v3? If v2, we cannot adopt CLI 3.x until the server migration is scheduled — and we should pin ^2.7 deliberately.
2. Does any .rr.yaml in any environment reference the removed tcp, websockets, broadcast, or reload plugins? What replaces them in our topology (websocket fan-out, zero-downtime reload)?
3. Do we have custom PHP classes extending or importing Spiral\RoadRunner\Console\*? If yes, they need rewriting before upgrade, not after.
4. Are binary downloads in CI pinned to an explicit version, or wildcard? Wildcard now means "install RR3" — an unintended upgrade vector.
5. Do any CI jobs or pipelines run PHP < 8.2, and is the Laravel version able to move to 8.2+ in the same window?
6. Are we on GitHub.com or GHES, and who owns rotating DLOAD_TOKEN_<HOST>?

Integration Approach

Stack fit:

• Laravel + RoadRunner 3: viable target, but the .rr.yaml and plugin model change is the real integration work; the CLI is the easy part.
• Binary management: DLoad-based downloads are a net improvement for reproducible builds, provided versions are pinned explicitly rather than wildcard-filtered.
• New config sections (nsq, kafka, google_pub_sub, centrifuge, protoreg): a genuine capability unlock for teams moving queues/broadcast off the removed plugins — this is the migration path for broadcast/websockets, not a workaround.

Migration path:

1. Decide the target state first — stay on RR2 (roadrunner-php/cli:^2.7, freeze binary downloads to 2.x) or commit to RR3 (CLI ^3.0). Do not run mixed.
2. Pin everything — explicit CLI constraint, explicit RoadRunner binary version in get-binary invocations, no wildcard in any pipeline.
3. Audit .rr.yaml across dev/staging/prod for the four removed plugins; design replacements (Centrifuge/Kafka/NSQ for broadcast; platform-level reload strategy).
4. PHP 8.2 + Symfony 6.4 verification in the same change window, before touching the CLI.
5. Grep for Spiral\RoadRunner\Console in application and tooling code; rewrite or delete any extension points.
6. Regenerate config in a branch and diff against the current .rr.yaml — review the RR3 output before it ever reaches a running deployment.
7. Canary: one non-production worker pool on RR3 + CLI 3, then staging, then a single production pool.

Compatibility:

• Laravel 10.x/11.x on PHP 8.2+: clean target.
• Laravel 9.x / PHP 8.0–8.1: blocked; requires app upgrade first.
• RoadRunner 2.x server: blocked; CLI 3.x generates RR3 config only.
• GHES CI: works only after RR_GITHUB_API_URL and DLOAD_TOKEN_<HOST> are corrected.
• Sequencing: PHP → Laravel → RoadRunner server + config rewrite → CLI 3.x. The CLI is last, not first.

Operational Impact

Maintenance: Active development continues and the package is clearly being steered toward RR3, which is a good long-term signal but a poor short-term one for anyone mid-migration. The internal-namespace decision means future minor releases may restructure code without SemVer protection — we should consume only the CLI binaries and generated config, never the classes. Budget recurring effort for tracking RR3 releases rather than assuming this is a one-time upgrade.

Support: Fallback is roadrunner-php/cli ^2.7, which remains valid while the server is RR2 — keep that constraint documented and reversible. For troubleshooting, the --verbose workflow still applies; the DLoad documentation now covers musl selection and DLoad side effects, which is the fastest path when binary downloads misbehave. One quiet improvement worth noting: config generation no longer writes a broken .rr.yaml on failure, removing a historically nasty support case.

Scaling: This is where the release has real operational weight. Removing tcp, websockets, broadcast, and reload from RR3 means our scaling and deployment story changes: websocket fan-out needs a dedicated broker (Centrifuge being the natural fit given the new config section), and zero-downtime reload moves from a RoadRunner plugin to platform-level orchestration. Capacity planning for worker pools and the CLI surface itself is unchanged; the messaging layer is not.

Failure modes:

• Silent RR3 binary pull: wildcard version filters installing RR3 under an RR2 runtime — worker startup failures or hangs, with a confusing error surface.
• Config regeneration overwrite: newly RR3-shaped config written into an RR2 deployment, producing plugins the server ignores or rejects.
• Autoload fatals: custom commands or option classes extending removed base classes fail at boot, taking down the console entrypoint entirely.
• GHES download failures: incorrect RR_GITHUB_API_URL suffix or stale GITHUB_TOKEN — CI breaks at binary fetch, which reads as an infrastructure fault rather than a package change.
• PHP version skew: CLI resolves locally under 8.2 while a prod container sits on 8.1, passing build and failing at runtime.

Ramp-up: No longer "low effort." Realistically: low engineering effort to install, medium-to-high effort to migrate safely, dominated by the RR3 server move and .rr.yaml rewrite rather than by the package itself. Plan an audit sprint, a staging canary, and a documented rollback to the 2.7 line before scheduling the production cutover.