gem-hunter

Command line tool to install RoadRunner binaries and generate configs

This package provides the rr console command for PHP projects that run on RoadRunner: it downloads the RoadRunner server binary and the gRPC code generation tools (buf, protoc, protoc-gen-php-grpc) built for your environment and generates a starter .rr.yaml configuration.

composer require roadrunner/cli

Download the latest RoadRunner binary for your operating system and architecture into the project root, along with an example .rr.yaml:

vendor/bin/rr get-binary

Then start the server:

./rr serve

See the RoadRunner documentation for the configuration reference.

Generating gRPC code with buf generate takes three binaries: buf, protoc (buf runs its built-in PHP generator) and protoc-gen-php-grpc. Download all of them into the current directory (--location picks another one):

vendor/bin/rr get-grpc-tools

 google/protobuf v5.36.2 -> protoc ^36.0

 Versions:
   - buf:                 ^1
   - protoc:              ^36.0
   - protoc-gen-php-grpc: 3.*

The protoc version follows the protobuf runtime of the project, since the generated code is only guaranteed to work with the runtime of the same protoc major: the PHP runtime minor is the protoc major (google/protobuf 4.33.x takes protoc 33.x, 5.36.x takes 36.x; up to 3.20 both shared one version). The runtime is ext-protobuf when it is loaded in the PHP running rr, or else the google/protobuf package installed in the project (the nearest directory up from the working one with a composer.json, read from its vendor/composer/installed.json; a project that is not installed yet counts as having none); when the two need different protoc majors, a warning names both, as the project may run on a PHP without the extension; without either, or when its version does not tell the protoc major (e.g. a branch), a protoc already in the location stays whatever its version, or else the latest one is installed. --protoc, --buf and --plugin (for protoc-gen-php-grpc) take a version constraint each, e.g. --protoc=^33.0. A buf or protoc already in the location stays only when it runs and the version it reports with --version satisfies the constraint; otherwise it is replaced. protoc-gen-php-grpc is downloaded on every run. Only the protoc executable is installed, without the include/ directory of its release: buf supplies the well-known types (google/protobuf/timestamp.proto and the like) itself, while a direct protoc call that imports them needs -I pointing to them.

• get-binary (or get) - allows to install the latest version of the RoadRunner compatible with your environment (operating system, processor architecture, runtime, etc...). Also, this command creates an example .rr.yaml configuration file. If the command is used without the plugin and preset options, a configuration with the default plugins (rpc, server, http, jobs, kv, metrics) is created. Using the plugin option (shortcut p) can create an example configuration file with only plugins needed. For example, with http plugin only: get-binary -p http, http and jobs: get-binary -p http -p jobs. Available plugins: amqp, beanstalk, boltdb, centrifuge, endure, fileserver, google_pub_sub, grpc, http, jobs, kafka, kv, logs, metrics, nats, nsq, otel, protoreg, redis, rpc, server, service, sqs, status, temporal. Using the preset option can create an example configuration file with popular plugins for different typical tasks. For example, with web preset: get-binary --preset web. Available presets: web (contains plugins http, jobs). Use --no-config to skip the configuration file.
• make-config - creates the .rr.yaml configuration file without downloading the binary. Accepts the same plugin and preset options.
• get-grpc-tools - installs buf, protoc and protoc-gen-php-grpc, the binaries buf generate needs to generate gRPC code, see gRPC tools. The versions default to buf 1.x, the protoc major the project's protobuf runtime supports and protoc-gen-php-grpc of the RoadRunner line get-binary installs; --buf, --protoc and --plugin override them. Without asking, it keeps a binary already in the location only when its version satisfies the constraint, see gRPC tools.
• download-protoc-binary - deprecated, use get-grpc-tools. Installs only the protoc-gen-php-grpc plugin, not protoc itself.
• versions - displays a list of available RoadRunner binary versions.

The binary commands accept --stability (-s), --os (-o) and --arch (-a) options. get-binary, download-protoc-binary and versions take the version constraint as --filter (-f), get-grpc-tools as --buf, --protoc and --plugin. For get-binary and download-protoc-binary * means >=3.0 <2000 and any other || alternative without an upper bound gets <2000, so the calendar releases have to be named explicitly, e.g. 2025.* or >=2025; get-grpc-tools applies the same to --plugin and takes --buf/--protoc as they are. get-binary, get-grpc-tools and download-protoc-binary also accept --location (-l, target directory, the current one by default) and download the binaries with DLoad; a project's dload.xml does not affect them.

On a musl host such as Alpine they install the musl build of Linux on their own, even with --os=linux; --os=unknown-musl forces the musl build from any host.

DLoad comes with its own vendor/bin/dload and keeps a version registry in the user cache: ~/.cache/dload, $XDG_CACHE_HOME/dload when that is set, %LOCALAPPDATA%\dload\cache on Windows. DLOAD_CACHE_DIR moves it, DLOAD_CACHE_TTL=0 turns it off.

Releases are fetched from the GitHub API at RR_GITHUB_API_URL, https://api.github.com by default. For get-binary, get-grpc-tools and download-protoc-binary it is either https://api.github.com or a GitHub Enterprise Server API URL ending with /api/v3 (e.g. https://ghe.example.com/api/v3), which then has to serve bufbuild/buf and protocolbuffers/protobuf for get-grpc-tools too; versions also accepts a mirror.

All commands pick the API token the same way, to avoid the rate limits:

• the public GitHub gets DLOAD_TOKEN_GITHUB_COM, or GITHUB_TOKEN when that one is not set;
• any other server gets only its own DLOAD_TOKEN_<HOST>: the host upper-cased, . as _, - as __, a non-default port after ___ (e.g. DLOAD_TOKEN_GHE_EXAMPLE_COM, DLOAD_TOKEN_GHE_EXAMPLE_COM___8443); GITHUB_TOKEN never leaves the public GitHub;
• over plain http a token is sent only to a loopback host, and it is never carried over a redirect to another host.