Grpc Client Laravel Package

Product Decisions This Supports

• Build vs. buy for gRPC client plumbing. If a roadmap item requires our PHP services to call gRPC backends (internal service mesh, third-party vendor APIs, ML inference endpoints), this package removes the build cost of a hand-rolled client. We buy the transport, interceptor pipeline, and config DTOs instead of writing them.
• Roadmap scoping: "consume gRPC" vs. "full gRPC platform." This is a client-only library. It supports the decision to ship a consumer integration (e.g., calling a recommendation service or a payments gateway) without committing to running PHP as a gRPC server. Conversely, it does not support a "PHP as first-class gRPC service provider" roadmap item — that still needs spiral/roadrunner-bridge + server-side tooling.
• Architecture/interop decisions. Because it enforces .proto-generated typed interfaces, adopting it is effectively a decision to adopt protobuf contracts for a given integration. That's a strategic call (schema governance, contract review process, codegen in CI) worth making explicitly rather than implicitly.
• Resilience investment as configuration, not code. Timeouts, retries with backoff, multi-endpoint failover/rotation, and auth metadata injection are all supported via composable interceptors. This lets us price reliability (SLO commitments, retry budgets) as a config change rather than an engineering sprint.
• Framework-alignment decision. Choosing this package is a soft vote for the Spiral/RoadRunner ecosystem. Teams already there get DI integration for free (spiral/roadrunner-bridge bundles it since 4.0); teams on Laravel/Symfony should price in integration work.
• Use cases this actually unlocks: synchronous service-to-service calls in a RoadRunner-hosted PHP app, gRPC access to third-party APIs that only expose gRPC, internal admin/back-office tools calling high-throughput backend services, and gradual migration off REST for a specific high-volume path.
• Scope reduction elsewhere. Immutable with* client derivation (a pre-configured base client, then derived variants) means we can centralize client configuration in one place — a small but real reduction in configuration-drift risk and per-team boilerplate.
• Tooling/DevEx decision. It requires the PECL grpc extension plus protoc with protoc-gen-php-grpc. That's a genuine platform decision: our base container image and CI runners need changes, and that cost should land on the platform/infra roadmap, not be discovered by a feature team mid-sprint.

When to Consider This Package

Consider it when:

• Our stack is already Spiral Framework and/or RoadRunner — the integration path is a one-line bootloader (or zero, via roadrunner-bridge 4.0+), and the container resolves typed service interfaces directly.
• We need a client-side-only gRPC integration with a small, familiar API (Guzzle-like GrpcClient::create()), and we want to avoid adopting a heavier framework dependency just for transport.
• We control or can mandate the .proto contracts and can generate PHP interfaces with protoc-gen-php-grpc in CI.
• We need retries, timeouts, auth metadata, and endpoint failover as first-class, composable concerns rather than ad-hoc per-call code.
• We're willing to accept pre-1.0 API churn: all published versions are 1.0.0-alpha* / rc*, and the alpha notes explicitly caution that public signatures may change. Pin versions and keep the blast radius to one integration.
• We can guarantee the PECL grpc extension in dev, CI, and production images (or we're prepared to own that build work).

Look elsewhere when:

• We need mature, widely-adopted dependencies. 40 GitHub stars, zero listed dependents, and a single primary author signal low ecosystem validation. This is a "one maintainer, small community" risk — mitigate with a vendored fork plan or a hard fallback.
• We need first-class observability: there's no native OpenTelemetry or structured logging integration. Interceptors can be extended for it, but we'd be building that ourselves.
• We need per-service interceptors on a non-Spiral stack — that path requires ServiceClientProvider + GrpcClientConfig (i.e., leaning on Spiral's container), so a Laravel or Symfony team gets the standalone client only, with a lower feature ceiling.
• We need gRPC-Web, browser clients, or server-side gRPC — out of scope for this package.
• We can't own the extension/protoc toolchain, or the target environment is constrained (shared hosting, managed PHP runtimes, locked base images).
• The integration is small enough that HTTP/JSON or an existing REST SDK already covers it — introducing gRPC + protobuf codegen + a PECL extension for one endpoint is not worth the operational tax.
• We need long-term support guarantees. There's no stated LTS or security-response policy; that's a risk we'd have to accept explicitly.

How to Pitch It (Stakeholders)

For executives (the one-paragraph version): This is a lightweight, MIT-licensed PHP client for gRPC — the protocol many of our backend services and vendors are moving to. It lets our PHP services call gRPC endpoints with typed contracts, built-in retries and timeouts, and multi-endpoint failover, using a small and clean API. The cost is low and the license is permissive; the main asks are a small platform investment (PHP's gRPC extension and protoc codegen must be in our images and CI) and a tolerance for a young library that is still pre-1.0. Recommendation: adopt for a bounded pilot on one integration where the protocol is already gRPC, not as a company-wide standard yet.

For engineering (the framing that matters):

• Concrete wins: a Guzzle-like GrpcClient::create() for standalone use; typed service access by generated interface; an interceptor pipeline for timeouts, retries/backoff, auth metadata, and connection rotation — all configured via DTOs and createConfig() factories rather than bespoke code. Immutable with* methods let us derive pre-configured clients safely, and interceptors are recreated per request and container-scoped, which is exactly the behavior we want under RoadRunner's long-running workers.
• What it asks of us: the PECL grpc extension in every environment; protoc-gen-php-grpc in the build; a pinned version because the API is still 1.0.0-rc*.
• What it deliberately doesn't do: no native OpenTelemetry, no per-service interceptors in standalone mode, and no server-side gRPC.
• Risk we're underwriting: a small, single-maintainer project. Mitigation is a narrow pilot, a version pin, a thin internal wrapper around our calls so the client is swappable, and a documented exit path.

Ask: approval for a two-to-three week pilot on one existing gRPC integration, platform time to add the extension and codegen to CI/base images, and a review checkpoint before any second integration adopts it.