Roadrunner Cli Laravel Package

Product Decisions This Supports

• Forces a roadmap decision on RoadRunner v3 migration: v3.0.0 of this CLI is the first release that generates configuration RoadRunner 3 accepts, and it pins the version filters to the 3.x line (wildcard now installs 3.0+). Teams still on RoadRunner 2 can no longer treat CLI upgrades as routine—plan a paired upgrade (server + CLI) or pin the CLI to the 2.7.x line.
• Resets the build-vs-buy calculation: the CLI now delegates binary downloads to DLoad, adds nsq, kafka, google_pub_sub, centrifuge and protoreg configuration sections, and drops the tcp, websockets, broadcast and reload plugins. The surface area covered out-of-the-box is larger, but any internal scripting that depended on removed plugins must be rewritten or retired.
• Raises the platform floor as an explicit cost: PHP 8.2+ and symfony/console/symfony/http-client 6.4+ are now required. This is a portfolio-level dependency decision (runtime upgrade, CI image refresh), not a per-project one—budget it once, centrally.
• Constrains extensibility by design: nearly everything moved into Internal\*, commands and Configuration\Generator are final, and the Archive/Repository namespaces (including Version1\StaticRepository) were removed. Any product extension built on the old public API is now unsupported; treat this as a signal to consume the CLI as a black-box tool, not a library.
• Changes enterprise/GHES integration mechanics: RR_GITHUB_API_URL must be https://api.github.com or end in /api/v3, and GHES tokens now come from DLOAD_TOKEN_<HOST> instead of GITHUB_TOKEN. Self-hosted and air-gapped pipelines need configuration and secret-management updates before upgrade.
• Improves trust in generated artifacts: .rr.yaml is no longer written when generation fails, removing a class of silent misconfiguration that previously surfaced late in deployment.

When to Consider This Package

✅ Adopt when:

• You are standardizing on RoadRunner 3 and want the CLI's generated .rr.yaml to be valid for it—this release exists primarily to make that safe.
• Your platform baseline is PHP 8.2+ with symfony/console and symfony/http-client 6.4+ (which keeps modern Symfony, including 8.x, viable), and you can absorb that floor.
• You need the newer plugin surface—Kafka, NSQ, Google Pub/Sub, Centrifuge, protobuf registry—reflected in generated configuration rather than hand-maintained.
• You run GitHub Enterprise Server and want first-class token handling per host, or you need RR_GITHUB_API_URL overrides for proxied/offline environments.
• You rely on DLoad-mediated binary downloads and can accept its documented side effects (per the new docs on musl selection).

❌ Look elsewhere (or stay on 2.7.x) when:

• You are still on RoadRunner 2 and cannot migrate in the current planning horizon—2.7.x remains the last line compatible with your runtime; do not upgrade the CLI.
• You depend on the removed plugins (tcp, websockets, broadcast, reload) or on any removed/now-internal API: Console\Archive, Console\Repository, Command\OptionInterface, Environment\Enum, the Environment\*Factory classes, Command::getRepository(), Command::confirm(), or VersionFilterOption::find()/choices(). These have no compatibility shim.
• Your automation subclasses commands or the configuration generator—both are now final, and commands extend Symfony's directly rather than the removed abstract base.
• You are below PHP 8.2 or pinned to symfony/console/http-client under 6.4.
• Existing internal tooling already covers RoadRunner lifecycle management and you gain nothing from the new config sections.
• Project doesn't involve PHP backend services.

How to Pitch It (Stakeholders)

Executives: "A major release (3.0.0) of the RoadRunner CLI is out: it aligns our tooling with RoadRunner 3 and expands coverage to Kafka, NSQ, Google Pub/Sub and Centrifuge—still MIT-licensed and zero-cost. Two things need a decision, not just an upgrade: it requires PHP 8.2+ and Symfony 6.4+, and it is deliberately not backward compatible—removed plugins, a now-internal API, and new enterprise GitHub token handling. Recommendation: fund one coordinated platform bump (runtime images, CI, secrets) and migrate RoadRunner 2 and this CLI together. Attempting a partial upgrade is where the risk sits, not in the tool itself."

Engineering: "3.0.0 is a breaking release. Practical impact: minimum PHP 8.2; symfony/console and symfony/http-client 6.4+; the wildcard version filter now installs RoadRunner 3.0+, so CLI and server must move together. The tcp, websockets, broadcast and reload plugins are gone (RoadRunner 3 doesn't ship them), Command, Configuration, Downloader and Environment internals moved to Internal\* and are off-limits, commands and Configuration\Generator are final, and Archive/Repository plus Version1\StaticRepository were deleted. RR_GITHUB_API_URL is now constrained, and GHES tokens move to DLOAD_TOKEN_<HOST>. Upside: valid RoadRunner 3 config generation (including the fix that skips writing .rr.yaml on failure), DLoad-based downloads, and the expanded plugin sections. Audit your pipeline for removed env vars, plugin references, and any code reaching into the old API before you bump the constraint."