RoadRunner gRPC plugin enables PHP applications to communicate with gRPC clients.
It consists of two main parts:
protoc-plugin protoc-gen-php-grpc: This is a plugin for the protoc compiler that generates PHP code from a gRPC
service definition file (.proto). It generates PHP classes that correspond to the service definition and message
types. These classes provide an interface for handling incoming gRPC requests and sending responses back to the
client.
gRPC server: This is a server that starts PHP workers and listens for incoming gRPC requests. It receives
requests from gRPC clients, proxies them to the PHP workers, and sends the responses back to the client. The server
is responsible for managing the lifecycle of the PHP workers and ensuring that they are available to handle requests.
Protoc-plugin
The first step is to define a .proto file that describes the gRPC service and messages that your PHP application will
handle.
In our documentation, we will use the following example of a .proto file that is stored in the <app>/proto
directory:
proto/helloworld.proto
syntax = "proto3";
option go_package = "proto/greeter";
option php_namespace = "GRPC\\Greeter";
option php_metadata_namespace = "GRPC\\GPBMetadata";
package helloworld;
// The greeting service definition.
service Greeter {
// Sends a greeting
rpc SayHello (HelloRequest) returns (HelloReply) {}
}
// The request message containing the user's name.
message HelloRequest {
string name = 1;
}
// The response message containing the greetings
message HelloReply {
string message = 1;
}
It defines a simple gRPC service called Greeter that takes a name as input and returns a greeting.
The php_namespace and php_metadata_namespace options allow you to specify the namespaces to use in the generated DTO
and Service interface.
Generating PHP code
After defining the proto file, you need to generate the PHP files using the protoc compiler and
the protoc-gen-php-grpc plugin. You can install the plugin binary using Composer or download a pre-built binary from
the GitHub releases page.
The simplest way to get the latest version of protoc-gen-php-grpc plugin is to download one of the pre-built release
binaries on the GitHub releases page.
Just download the appropriate archive from the release page and extract it into your desired application directory.
If you use Composer to manage your PHP dependencies, you can install the spiral/roadrunner-cli package to download the
latest version of protoc-gen-php-grpc plugin to your project's root directory.
Install the package
composer require spiral/roadrunner-cli
And run the following command to download the latest version of the plugin
./vendor/bin/rr download-protoc-binary
Server binary will be available at the root of your project.
PHP's extensions php-curl and php-zip are required. Check with php --modules your installed extensions.
Once the plugin is installed, you can use the protoc command to compile the proto file into PHP files.
Note that you need to optionally replace <your_org_name> and <your_project_name> with your organization and project names created on the BUF website.
In the deps section, you can specify the dependencies that your .proto file relies on. In this example, we're using a dependency from the Google APIs repository.
Also, you may configure the linting and breaking changes rules.
As you can see, the buf.gen.yaml file specifies the plugins that will be used to generate the code. In this example, we're using the buf.build/community/roadrunner-server-php-grpc plugin to generate PHP gRPC services.
Also, you may generate code for other languages like Go and Python.
PHP Client
The RoadRunner gRPC plugin comes with a convenient PHP package that simplifies the process of integrating the plugin
with your PHP application.
Installation
You can install the package via Composer using the following command:
composer require spiral/roadrunner-grpc
Implement Service
Next, you will need to create a PHP class that implements the Greeter service defined in the .proto file. This class
should implement the GRPC/Greeter/GreeterInterface.
Here's an example:
Greeter.php
<?php
use Spiral\RoadRunner\GRPC;
use GRPC\Greeter\GreeterInterface;
use GRPC\Greeter\HelloRequest;
use GRPC\Greeter\HelloReply;
final class Greeter implements GreeterInterface
{
public function SayHello(GRPC\ContextInterface $ctx, HelloRequest $in): HelloReply
{
$greeting = "Hello " . $in->getName() . "!";
return new HelloReply([
'message' => $greeting
]);
}
}
Usage
To use the Greeter service, you can create a PHP worker that registers the service with the gRPC server.
Here's an example of how to do this:
grpc-worker.php
<?php
use GRPC\Greeter\GreeterInterface;
use Spiral\RoadRunner\GRPC\Invoker;
use Spiral\RoadRunner\GRPC\Server;
use Spiral\RoadRunner\Worker;
require __DIR__ . '/vendor/autoload.php';
require 'Greeter.php';
$server = new Server(new Invoker(), [
'debug' => false, // optional (default: false)
]);
$server->registerService(GreeterInterface::class, new Greeter());
$server->serve(Worker::create());
After creating the worker, you need to configure RoadRunner to register the proto/helloworld.proto service.
You can define command to start server in the server.command section:. It will be used to start PHP workers for all
registered plugins, such as grpc, http, jobs, etc.
You can also define command to start server in the grpc.pool.command section to separate server and grpc workers.
You can define multiple proto files in the proto section.
After configuring the server, you can start it using the following command:
./rr serve
This will start the gRPC server and make the Greeter service available for remote clients to call. You can use any gRPC
client library in any language that supports gRPC to call the SayHello method.
To quickly verify your code's correctness, you can install grpc-client-cli which
provides an interactive CLI tool for talking to gRPC services.
To access the Greeter service with grpc-client-cli run the following in a terminal:
It will provide some interactive prompts asking you what service and method you want to call
? Choose a service: [Use arrows to move, type to filter]
→ helloworld.Greeter
? Choose a method: [Use arrows to move, type to filter]
[..]
→ SayHello
You will then be prompted to manually form the JSON payload it expects and upon pressing enter, your Greeter service
should respond in an amicable manner:
Message json (type ? to see defaults): {"name":"Roadrunner"}
{
"message": "Hello Roadrunner!"
}
On the PHP side, you should see that the successful request has been logged:
2025-03-28T10:04:06+0000 DEBUG server req-resp mode {"pid": 81551}
2025-03-28T10:04:06+0000 DEBUG grpc method was called successfully {"method": "/helloworld.Greeter/SayHello", "start": "2025-03-28T10:04:06+0000", "elapsed": 0}
Congratulations on being able to communicate over gRPC to PHP using Roadrunner!
Metrics
RoadRunner has a metrics plugin that provides metrics for the gRPC server, which can be used with
Prometheus and a preconfigured Grafana dashboard
version: "3"
grpc:
# GRPC address to listen
#
# This option is required
listen: "tcp://127.0.0.1:9001"
# Proto file to use, multiply files supported [SINCE 2.6]. As of [2023.1.4], wilcards are allowed in the proto field.
#
# This option is required
proto:
- "*.proto"
- "first.proto"
- "second.proto"
# GRPC TLS configuration
#
# This section is optional
tls:
# Path to the key file
#
# This option is required
key: ""
# Path to the certificate
#
# This option is required
cert: ""
# Path to the CA certificate, defines the set of root certificate authorities that servers use if required to verify a client certificate. Used with the `client_auth_type` option.
#
# This option is optional
root_ca: ""
# Client auth type.
#
# This option is optional. Default value: no_client_certs. Possible values: request_client_cert, require_any_client_cert, verify_client_cert_if_given, require_and_verify_client_cert, no_client_certs
client_auth_type: no_client_certs
# Maximum send message size
#
# This option is optional. Default value: 50 (MB)
max_send_msg_size: 50
# Maximum receive message size
#
# This option is optional. Default value: 50 (MB)
max_recv_msg_size: 50
# MaxConnectionIdle is a duration for the amount of time after which an
# idle connection would be closed by sending a GoAway. Idleness duration is
# defined since the most recent time the number of outstanding RPCs became
# zero or the connection establishment.
#
# This option is optional. Default value: infinity.
max_connection_idle: 0s
# MaxConnectionAge is a duration for the maximum amount of time a
# connection may exist before it will be closed by sending a GoAway. A
# random jitter of +/-10% will be added to MaxConnectionAge to spread out
# connection storms.
#
# This option is optional. Default value: infinity.
max_connection_age: 0s
# MaxConnectionAgeGrace is an additive period after MaxConnectionAge after
# which the connection will be forcibly closed.
max_connection_age_grace: 0s8h
# MaxConnectionAgeGrace is an additive period after MaxConnectionAge after
# which the connection will be forcibly closed.
#
# This option is optional: Default value: 10
max_concurrent_streams: 10
# After a duration of this time if the server doesn't see any activity it
# pings the client to see if the transport is still alive.
# If set below 1s, a minimum value of 1s will be used instead.
#
# This option is optional. Default value: 2h
ping_time: 1s
# After having pinged for keepalive check, the server waits for a duration
# of Timeout and if no activity is seen even after that the connection is
# closed.
#
# This option is optional. Default value: 20s
timeout: 200s
# Usual workers pool configuration
pool:
# Debug mode for the pool. In this mode, pool will not pre-allocate the worker. Worker (only 1, num_workers ignored) will be allocated right after the request arrived.
#
# Default: false
debug: false
# Override server's command
#
# Default: empty
command: "php my-super-app.php"
# How many worker processes will be started. Zero (or nothing) means the number of logical CPUs.
#
# Default: 0
num_workers: 0
# Maximal count of worker executions. Zero (or nothing) means no limit.
#
# Default: 0
max_jobs: 0
# Timeout for worker allocation. Zero means 60s.
#
# Default: 60s
allocate_timeout: 60s
# Timeout for the reset timeout. Zero means 60s.
#
# Default: 60s
reset_timeout: 60s
# Timeout for worker destroying before process killing. Zero means 60s.
#
# Default: 60s
destroy_timeout: 60s
OTLP support in the gRPC plugin: [>=2023.3.8]
In the v2023.3.8 we added experimental support for the OTLP protocol in the gRPC plugin. Stable since v2024.1.1. To enable it, you need to activate otel plugin by adding the following lines to the .rr.yaml file:
.svg?alt=media&token=f7053376-fa86-4721-a95b-27de12e75d6b)
