linkfast / exengine-grpc

1.0.0-a1 2026-10-16 04:45 UTC

Requires

• php: >=8.2
• google/protobuf: ^5.36
• linkfast/exengine: ^1.3.0-a4
• linkfast/exengine-roadrunner: ^1.0.0-a3
• spiral/roadrunner-grpc: ^3.7

Requires (Dev)

• phpunit/phpunit: ^10.5 || ^11.0 || ^12.0 || ^13.0

Suggests

• ext-protobuf: Faster protobuf encoding than the PHP implementation of google/protobuf.

MIT

• Giancarlo A. Chiappe

• protobuf
• exengine
• gRPC
• roadrunner
• exengine-extension

Published on Packagist.org on 2026-10-16 09:49 UTC

README

gRPC services for the ExEngine microframework, served by RoadRunner's grpc plugin. Contract-first: the services come from .proto files, and exen generates the code.

© LinkFast S.A. (https://linkfast.io) · MIT License

In development (pre-releases 1.0.0-aN).

Requirements

• PHP 8.2 or higher, with ext-sockets (RoadRunner workers)
• ExEngine 1.3.0-a4 or higher and linkfast/exengine-roadrunner 1.0.0-a3 or higher
• protoc to generate the message classes (exen protoc:install downloads it)
• Optional: ext-protobuf, faster than the PHP implementation of google/protobuf

Installation

exen extension:add linkfast/exengine-grpc:^1.0.0-a1

Then add the contract with exen, which runs protoc for the message classes and writes the services:

exen contract:add orders.proto

How it works

RoadRunner's grpc plugin listens for gRPC calls (.rr.yaml, grpc: section) and starts PHP workers with RR_MODE=grpc. The project's worker.php (ExEngine\RoadRunner\Worker::run()) hands those workers to this extension, which registers the services of the contracts in RoadRunner's gRPC server:

• The contract's Extension implements GrpcContract: each generated service (a ServiceAdapter with the service NAME of the .proto file and one method per RPC) and the application's implementation.
• For each call, the implementation is created with dependency injection and receives the request message and a Call: request metadata (metadata('authorization')), response headers and trailers.
• An implementation throws GrpcError (GrpcError::notFound('...'), invalidArgument, permissionDenied, ...) for an error the client should see, with its status. Any other exception is answered as INTERNAL with the message "Internal error" (and logged), unless grpc.debug is on.
• After each call, ExEngine\RoadRunner\WorkDone resets the services marked #[Service] that implement Resettable.

Unary RPCs are supported; RoadRunner's PHP workers do not serve streaming RPCs.

Configuration

Key	Default	Description
grpc.debug	false	Send the message of unexpected exceptions to clients (development only)

The address, the .proto files and the worker pool are RoadRunner settings (.rr.yaml, grpc: section).

Development

composer install
vendor/bin/phpunit

The end-to-end test runs when RR_BINARY points to an rr binary. The message classes of the test fixture (tests/Fixtures/Proto) come from tests/Fixtures/contracts/orders.proto:

protoc -I tests/Fixtures/contracts --php_out=tests/Fixtures/Proto tests/Fixtures/contracts/orders.proto

License

MIT, see LICENSE.