feat: add get-grpc-tools command

README.md

@@ -20,7 +20,7 @@
 
 <br />
 
-This package provides the `rr` console command for PHP projects that run on [RoadRunner](https://roadrunner.dev): it downloads the RoadRunner server binary and `protoc-gen-php-grpc` plugin built for your environment and generates a starter `.rr.yaml` configuration.
+This package provides the `rr` console command for PHP projects that run on [RoadRunner](https://roadrunner.dev): 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.
 
 > [!NOTE]
 > Version 3.x of `roadrunner/cli` targets RoadRunner v3: `rr get` downloads RoadRunner 3 by default. For RoadRunner 2025.x, use [`spiral/roadrunner-cli`](https://packagist.org/packages/spiral/roadrunner-cli) 2.x.
@@ -54,6 +54,25 @@ Then start the server:
 
 See the [RoadRunner documentation](https://docs.roadrunner.dev) for the configuration reference.
 
+### gRPC tools
+
+Generating gRPC code with `buf generate` takes three binaries: [`buf`](https://buf.build), `protoc` (buf runs its built-in PHP generator) and `protoc-gen-php-grpc`. Download all of them into the project root:
+
+```bash
+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 the `google/protobuf` package installed in the project in the working directory, or else `ext-protobuf`; without either, the latest protoc is installed. `--protoc`, `--buf` and `--plugin` (for `protoc-gen-php-grpc`) take a version constraint each, e.g. `--protoc=^33.0`.
+
 ## Commands
 
 - `get-binary` (or `get`) - allows to install the latest version of the RoadRunner compatible with
@@ -70,19 +89,23 @@ See the [RoadRunner documentation](https://docs.roadrunner.dev) for the configur
   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.
-- `download-protoc-binary` - allows to install the latest version of the `protoc-gen-php-grpc` file compatible with
-  your environment (operating system, processor architecture, runtime, etc...).
+- `get-grpc-tools` - installs `buf`, `protoc` and `protoc-gen-php-grpc`, the binaries `buf generate` needs to
+  generate gRPC code, see [gRPC tools](#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. Binaries already in the location are kept unless the overwrite is confirmed.
+- `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.
 
 ### Common options
 
-The binary commands accept `--filter` (`-f`, version constraint; 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`), `--stability` (`-s`), `--os` (`-o`), `--arch` (`-a`) and `--location` (`-l`, target directory) options. `get-binary` and `download-protoc-binary` download the binaries with [DLoad](https://github.com/php-internal/dload); a project's `dload.xml` does not affect them.
+The binary commands accept `--filter` (`-f`, version constraint; 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), `--stability` (`-s`), `--os` (`-o`), `--arch` (`-a`) and `--location` (`-l`, target directory) options. `get-binary`, `get-grpc-tools` and `download-protoc-binary` download the binaries with [DLoad](https://github.com/php-internal/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` 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`); `versions` also accepts a mirror.
+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:
 

bin/rr

@@ -12,6 +12,7 @@ declare(strict_types=1);
 
 use Spiral\RoadRunner\Console\DownloadProtocBinaryCommand;
 use Spiral\RoadRunner\Console\GetBinaryCommand;
+use Spiral\RoadRunner\Console\GetGrpcToolsCommand;
 use Spiral\RoadRunner\Console\MakeConfigCommand;
 use Spiral\RoadRunner\Console\VersionsCommand;
 use Spiral\RoadRunner\Version;
@@ -72,12 +73,14 @@ if (\method_exists($app, 'addCommand')) {
     $app->addCommand(new GetBinaryCommand());
     $app->addCommand(new VersionsCommand());
     $app->addCommand(new DownloadProtocBinaryCommand());
+    $app->addCommand(new GetGrpcToolsCommand());
     $app->addCommand(new MakeConfigCommand());
 } else {
     // For Symfony 7.3 and lower
     $app->add(new GetBinaryCommand());
     $app->add(new VersionsCommand());
     $app->add(new DownloadProtocBinaryCommand());
+    $app->add(new GetGrpcToolsCommand());
     $app->add(new MakeConfigCommand());
 }
 

src/DownloadProtocBinaryCommand.php

@@ -34,7 +34,7 @@
     public function __construct(?string $name = null, ?DLoadDownloader $downloader = null)
     {
         $this->downloader = $downloader ?? new DLoadDownloader();
         parent::__construct($name ?? 'download-protoc-binary');
 
         $this->os = new OperatingSystemOption($this);
         $this->arch = new ArchitectureOption($this);
@@ -46,7 +46,7 @@
     #[\Override]
     public function getDescription(): string
     {
-        return 'Install or update protoc-gen-php-grpc binary';
+        return 'Install or update protoc-gen-php-grpc binary (deprecated, use get-grpc-tools)';
     }
 
     #[\Override]
@@ -57,13 +57,13 @@
         $target = $this->location->get($input, $io);
         $os = $this->os->get($input, $io);
 
         $output->writeln('');
         $output->writeln(' Environment:');
         $output->writeln(\sprintf('   - Version:          <info>%s</info>', $this->version->get($input, $io)));
         $output->writeln(\sprintf('   - Stability:        <info>%s</info>', $this->stability->get($input, $io)));
         $output->writeln(\sprintf('   - Operating System: <info>%s</info>', $os));
         $output->writeln(\sprintf('   - Architecture:     <info>%s</info>', $this->arch->get($input, $io)));
         $output->writeln('');
 
         $binary = $target . ($os === OperatingSystem::OS_WINDOWS ? '/protoc-gen-php-grpc.exe' : '/protoc-gen-php-grpc');
 

src/GetBinaryCommand.php

@@ -42,7 +42,9 @@
     public function __construct(?string $name = null, ?DLoadDownloader $downloader = null)
     {
         $this->downloader = $downloader ?? new DLoadDownloader();
         parent::__construct($name ?? 'get-binary');
+        // Not left to Symfony's abbreviation lookup: `get` also abbreviates get-grpc-tools
+        $name === null and $this->setAliases(['get']);
 
         $this->os = new OperatingSystemOption($this);
         $this->arch = new ArchitectureOption($this);

src/GetGrpcToolsCommand.php

@@ -0,0 +1,236 @@
+<?php
+
+/**
+ * This file is part of RoadRunner package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Spiral\RoadRunner\Console;
+
+use Spiral\RoadRunner\Console\Environment\OperatingSystem;
+use Spiral\RoadRunner\Console\Internal\Downloader\DLoadDownloader;
+use Spiral\RoadRunner\Console\Internal\Environment\ProtobufRuntime;
+use Spiral\RoadRunner\Console\Internal\Environment\RoadRunnerVersion;
+use Spiral\RoadRunner\Console\Internal\Option\ArchitectureOption;
+use Spiral\RoadRunner\Console\Internal\Option\InstallationLocationOption;
+use Spiral\RoadRunner\Console\Internal\Option\OperatingSystemOption;
+use Spiral\RoadRunner\Console\Internal\Option\StabilityOption;
+use Symfony\Component\Console\Command\Command;
+use Symfony\Component\Console\Input\InputInterface;
+use Symfony\Component\Console\Input\InputOption;
+use Symfony\Component\Console\Output\OutputInterface;
+use Symfony\Component\Console\Style\StyleInterface;
+use Symfony\Component\Console\Style\SymfonyStyle;
+
+/**
+ * Downloads the binaries `buf generate` needs to generate gRPC code: buf, protoc and protoc-gen-php-grpc.
+ *
+ * @psalm-api
+ */
+final class GetGrpcToolsCommand extends Command
+{
+    private const BUF_CONSTRAINT = '^1';
+    private const ANY_VERSION = '*';
+
+    private OperatingSystemOption $os;
+    private ArchitectureOption $arch;
+    private StabilityOption $stability;
+    private InstallationLocationOption $location;
+    private DLoadDownloader $downloader;
+
+    /** @var \Closure(): ?ProtobufRuntime */
+    private \Closure $runtime;
+
+    /**
+     * @param (\Closure(): ?ProtobufRuntime)|null $runtime Finds the protobuf runtime of the project;
+     *        {@see ProtobufRuntime::detect()} in the working directory by default.
+     */
+    public function __construct(?string $name = null, ?DLoadDownloader $downloader = null, ?\Closure $runtime = null)
+    {
+        $this->downloader = $downloader ?? new DLoadDownloader();
+        $this->runtime = $runtime ?? static fn(): ?ProtobufRuntime => ProtobufRuntime::detect(\getcwd() ?: '.');
+        parent::__construct($name ?? 'get-grpc-tools');
+
+        $this->os = new OperatingSystemOption($this);
+        $this->arch = new ArchitectureOption($this);
+        $this->location = new InstallationLocationOption($this);
+        $this->stability = new StabilityOption($this);
+    }
+
+    #[\Override]
+    public function getDescription(): string
+    {
+        return 'Install or update buf, protoc and protoc-gen-php-grpc to generate gRPC code';
+    }
+
+    #[\Override]
+    public function execute(InputInterface $input, OutputInterface $output): int
+    {
+        $io = new SymfonyStyle($input, $output);
+
+        $target = $this->location->get($input, $io);
+        $os = $this->os->get($input, $io);
+        $arch = $this->arch->get($input, $io);
+        $stability = $this->stability->get($input, $io);
+
+        $output->writeln('');
+        $output->writeln(' Environment:');
+        $output->writeln(\sprintf('   - Stability:        <info>%s</info>', $stability));
+        $output->writeln(\sprintf('   - Operating System: <info>%s</info>', $os));
+        $output->writeln(\sprintf('   - Architecture:     <info>%s</info>', $arch));
+        $output->writeln('');
+
+        [$protoc, $derivedFrom] = $this->protocConstraint($input, $io);
+
+        $tools = [
+            'buf' => self::option($input, 'buf') ?? self::ANY_VERSION,
+            'protoc' => $protoc,
+            'protoc-gen-php-grpc' => self::option($input, 'plugin') ?? self::ANY_VERSION,
+        ];
+
+        $output->writeln(' Versions:');
+        foreach ($tools as $tool => $constraint) {
+            $output->writeln(\sprintf('   - %-20s <info>%s</info>', $tool . ':', $constraint));
+        }
+        $output->writeln('');
+
+        $failed = [];
+        foreach ($tools as $tool => $constraint) {
+            $binary = $target . '/' . $tool . ($os === OperatingSystem::OS_WINDOWS ? '.exe' : '');
+            if (! $this->checkExisting($tool, $binary, $io)) {
+                continue;
+            }
+
+            $code = $this->downloader->download(
+                software: $tool,
+                constraint: $constraint,
+                stability: $stability,
+                os: $os,
+                arch: $arch,
+                location: $target,
+                force: true,
+                output: $output,
+            );
+
+            if ($code === self::SUCCESS) {
+                continue;
+            }
+
+            $failed[] = $tool;
+            if ($tool === 'protoc' && $derivedFrom !== null) {
+                $io->error(\sprintf(
+                    'Could not install protoc %s, the version %s %s supports. '
+                    . 'If no protoc release matches it, choose one with --protoc=<constraint>.',
+                    $constraint,
+                    $derivedFrom->name,
+                    $derivedFrom->version,
+                ));
+            }
+        }
+
+        if ($failed !== []) {
+            $io->error('Not installed: ' . \implode(', ', $failed));
+
+            return self::FAILURE;
+        }
+
+        $io->success('gRPC tools are ready in ' . $target);
+
+        return self::SUCCESS;
+    }
+
+    #[\Override]
+    protected function configure(): void
+    {
+        $this->addOption(
+            'protoc',
+            null,
+            InputOption::VALUE_REQUIRED,
+            'Version constraint of protoc; by default the protoc major the installed google/protobuf or ext-protobuf supports',
+        );
+
+        $this->addOption(
+            'plugin',
+            null,
+            InputOption::VALUE_REQUIRED,
+            'Version constraint of protoc-gen-php-grpc',
+            RoadRunnerVersion::constraint(),
+        );
+
+        $this->addOption(
+            'buf',
+            null,
+            InputOption::VALUE_REQUIRED,
+            'Version constraint of buf',
+            self::BUF_CONSTRAINT,
+        );
+    }
+
+    /**
+     * @return non-empty-string|null
+     */
+    private static function option(InputInterface $input, string $name): ?string
+    {
+        /** @var mixed $value */
+        $value = $input->getOption($name);
+
+        return \is_string($value) && $value !== '' ? $value : null;
+    }
+
+    /**
+     * @return array{non-empty-string, ProtobufRuntime|null} The constraint and the runtime it is derived from.
+     */
+    private function protocConstraint(InputInterface $input, SymfonyStyle $io): array
+    {
+        $option = self::option($input, 'protoc');
+        if ($option !== null) {
+            return [$option, null];
+        }
+
+        $runtime = ($this->runtime)();
+        if ($runtime === null) {
+            $io->warning(\sprintf(
+                'Neither %s nor %s is installed: installing the latest protoc. Choose a version with --protoc=<constraint>.',
+                ProtobufRuntime::PACKAGE,
+                ProtobufRuntime::EXTENSION,
+            ));
+
+            return [self::ANY_VERSION, null];
+        }
+
+        $constraint = $runtime->protocConstraint();
+        if ($constraint === null) {
+            $io->warning(\sprintf(
+                'Can not tell the protoc version for %s %s: installing the latest protoc. Choose a version with --protoc=<constraint>.',
+                $runtime->name,
+                $runtime->version,
+            ));
+
+            return [self::ANY_VERSION, null];
+        }
+
+        $io->writeln(\sprintf(' %s <info>%s</info> -> protoc <info>%s</info>', $runtime->name, $runtime->version, $constraint));
+        $io->newLine();
+
+        return [$constraint, $runtime];
+    }
+
+    private function checkExisting(string $tool, string $binary, StyleInterface $io): bool
+    {
+        if (\is_file($binary)) {
+            $io->warning(\sprintf('%s binary file already exists!', $tool));
+
+            if (! $io->confirm('Do you want overwrite it?', false)) {
+                $io->note(\sprintf('Skipping %s installation...', $tool));
+
+                return false;
+            }
+        }
+
+        return true;
+    }
+}