Weave Code
Roadrunner Grpc Laravel Package
spiral/roadrunner-grpc
High-performance PHP gRPC server built on RoadRunner. Run PHP and Go services in one app with native gRPC compliance, TLS, middleware, Prometheus metrics, and protoc code generation. Map response error codes to PHP exceptions.
RoadRunner GRPC is an open-source (MIT) high-performance PHP gRPC server built on top of RoadRunner. It provides a fast, low-footprint proxy with a native Golang gRPC implementation, letting PHP and Golang services run together within a single application with minimal, plug-and-play configuration.
- Code generation via a
protocplugin, downloadable from the RoadRunner releases page - TLS setup, middleware, and server customization support
- Error management for transport, message, and worker failures, with response codes mapped to PHP exceptions
- Observability with built-in debug tools and Prometheus metrics
- Cross-platform, including Windows support
Frequently asked questions about Roadrunner Grpc
- How do I install RoadRunner GRPC in a Laravel application?
- Install the current package with composer require roadrunner/grpc; 3.8.0 renamed it from spiral/roadrunner-grpc, so replace the old requirement rather than adding the new one alongside it. Add the grpc block to your .rr.yaml, download the RoadRunner protoc plugin for code generation, and create a dedicated PHP worker entrypoint that boots Laravel and registers your generated service handlers. If any branch or template still references spiral/roadrunner-grpc, verify whether the old name aliases or replaces the new one before installing; otherwise you can end up with two packages and competing Spiral\RoadRunner\GRPC namespaces.
- Is spiral/roadrunner-grpc the same package as roadrunner/grpc?
- Yes at the code level: 3.8.0 renames the package identity from spiral/roadrunner-grpc to roadrunner/grpc while keeping the PHP worker-side handler contract and Spiral\RoadRunner\GRPC namespace. Composer treats the names as separate artifacts, so the practical question is whether the old name is marked abandoned with a replace or alias to the new one. Verify that before the first install and add a CI guard that fails if the legacy package appears in composer.lock; otherwise you risk class collisions or silently pinning a frozen package.
- Does roadrunner/grpc run a gRPC server entirely in PHP?
- No. It is the PHP handler SDK for the RoadRunner gRPC stack, not a standalone server: the Go RoadRunner plugin terminates HTTP/2 and gRPC, decodes protobuf payloads, and dispatches them to long-lived PHP workers implementing generated base classes. You still need the RoadRunner server, compatible google/protobuf and grpc extensions, and correct .rr.yaml configuration. That split is why the package is fast and low-footprint but also why RoadRunner becomes part of your runtime and deployment model.
- Which Laravel and PHP versions can use roadrunner/grpc?
- The package is framework-agnostic and does not ship Laravel-specific version constraints; Laravel compatibility follows from the PHP version supported by the release and your ability to run the app under RoadRunner instead of PHP-FPM. Check the exact PHP, protobuf, and grpc extension constraints in the package composer.json on Packagist for the version you pin. For Laravel, test your actual framework version inside a RoadRunner worker, because the runtime migration is the larger compatibility variable than the package name.
- How does protoc code generation work with RoadRunner GRPC?
- Define your services in .proto files, download the RoadRunner protoc plugin from the RoadRunner releases page, and run protoc with that plugin to generate PHP service base classes. You then implement thin handlers that extend those generated classes and return responses or throw exceptions that map to gRPC status codes. Keep the generated code and the roadrunner/grpc version in lockstep when you upgrade, because the worker contract and protobuf toolchain are version-coupled.
- Can I use Laravel middleware and auth inside RoadRunner gRPC handlers?
- Laravel HTTP middleware does not run on gRPC calls because the request does not pass through the HTTP kernel; gRPC workers are a separate entrypoint. Use RoadRunner gRPC middleware and interceptors for cross-cutting concerns such as authentication, logging, tenancy, and error mapping, and resolve Laravel services from the container in your worker bootstrap. You can share config, Eloquent, and domain services, but design handlers around explicit gRPC context rather than assuming HTTP session or route middleware behavior.
- What changes with RoadRunner v3 support in roadrunner/grpc 3.8.0?
- 3.8.0 adds RoadRunner v3 support, but it re-cuts the version lock across the PHP SDK, the RoadRunner server line, and the google/protobuf and grpc extensions. Treat that combination as a new compatibility matrix cell to test rather than a free upgrade, especially if you are already on RoadRunner 2024.x or 2025.x. Pin all three layers, run your gRPC integration tests, and validate worker startup, TLS, and metrics before rolling it out.
- How do I enable TLS, Prometheus metrics, and debug tools for RoadRunner gRPC?
- These are RoadRunner plugin features configured in the grpc block of .rr.yaml, not settings exposed by the PHP handler package itself. Configure TLS certificates and listen addresses in the RoadRunner config, enable the Prometheus metrics endpoint where your scraper can reach it, and turn on debug tooling only in non-production environments. Keep transport security and observability in the RoadRunner deployment config so they are reviewed with the rest of your runtime settings.
- What production risks should I expect from long-lived RoadRunner gRPC PHP workers?
- Persistent workers change the failure model: memory can grow across requests, state can leak between calls, workers can die silently, and your existing PHP-FPM observability may not cover them. Plan worker recycling and memory limits, health checks, structured logging, metrics, and graceful restarts, and test behavior under load and during deploys. RoadRunner upgrades are part of this operational contract, so they should not be deferred indefinitely.
- Is roadrunner/grpc actively maintained, and when should I choose an alternative?
- The project is MIT licensed, SpiralScout-backed, documented in the RoadRunner ecosystem, and shipping an active 3.8.x line with RoadRunner v3 support, which are positive maturity signals. Adoption signals are weaker after the rename: the new package name starts at near-zero Packagist dependents and search footprint, while most existing guidance points at spiral/roadrunner-grpc. Choose it when you are already committed to RoadRunner and can pin and test the PHP SDK, server, and protobuf toolchain together; otherwise compare it against a runtime and gRPC stack your team already operates, and update internal docs, templates, SBOM, and allowlists before adoption.
Weaver
How can I help you explore Laravel packages today?