Grpc Client Laravel Package

Technical Evaluation

Architecture fit

• Strong fit only if we are already a Spiral/RoadRunner shop. The package is the client half of Spiral's gRPC story: spiral/roadrunner-bridge >= 4.0.0 bundles it and supplies the bootloader and config flow. For a Spiral service that already exposes gRPC servers via protoc-gen-php-grpc, adopting the client adds no new conceptual model — same DI container, same interceptor idiom, same generated interface types.
• Weak fit for a general PHP/Laravel/vanilla-Symfony estate. Two hard constraints narrow it: (1) it requires the PECL grpc extension, and (2) it only accepts service interfaces generated by Spiral's protoc-gen-php-grpc plugin — not the stubs produced by the standard grpc/grpc + google/protobuf toolchain. This is not a drop-in replacement for an existing grpc/grpc PHP client; the generated contracts are different types. Any TPM assumption that "it's just a PHP gRPC client, we can point it at our existing protos" should be killed early.
• The new standalone GrpcClient (added in 1.0.0-rc2) materially improves fit outside Spiral. A Guzzle-like GrpcClient::create('host:port') with immutable with* derivation, withFactory() for container-based interceptor resolution, and a ServiceClientProvider path for other frameworks means Laravel adoption is feasible without pulling in Spiral's kernel. But the standalone path deliberately drops per-service interceptors — teams needing those must adopt the full GrpcClientConfig + ExecuteServiceInterceptors machinery, which is a meaningful complexity step up.
• The interceptor pipeline is the genuine product value. Timeout, retry, connection rotation, and scoped DI-aware interceptors give us retries, deadlines, auth-token propagation, and metadata handling without custom transport code. Immutable client derivation lets us publish one base client and derive environment- or tenant-specific variants safely — a real operational win.

Integration feasibility

• Mechanically straightforward: composer require spiral/grpc-client -W, install the PECL extension, generate interfaces, register the bootloader or instantiate the standalone client. Documentation is above average for a 40-star package — DTO config examples, interceptor ordering semantics, and a TLS example are all present.
• The blocking work is not the package, it is the platform: every runtime image, CI runner, and local dev environment must ship a compiled grpc extension at a version compatible with our PHP line. That is a one-time but non-trivial infrastructure task, and it is the single most likely source of schedule slip.
• Proto toolchain work is real: existing .proto files need generation through protoc-gen-php-grpc and the resulting interfaces wired into config. Budget this as a per-service cost, not a one-off.

Technical risk

• Pre-1.0 public API. The project is at 1.0.0-rc2; the alpha notes explicitly warn that public signatures may change. Despite a release as recent as 2026-03-19 and active maintenance by Spiral maintainers, we should assume breaking changes on the path to GA and pin exact versions.
• Adoption signal is thin on the surface and misleading underneath. 40 stars and 0 declared dependents looks alarming, but dependents under-count heavily here because roadrunner-bridge bundles the package rather than requiring it directly. Treat this as "unproven outside the vendor's own ecosystem" rather than "unused."
• Vendor concentration. Spiral controls the client, the protoc plugin, and the RoadRunner integration. That's coherent, but it means schema tooling and transport client move together — a lock-in vector worth naming explicitly to stakeholders.
• Observability is absent by default. No OpenTelemetry or structured logging integration; we will build tracing/logging interceptors ourselves. That is a known, bounded cost, but it must be in the estimate or the pilot will ship blind.
• Retry semantics carry product risk. RetryInterceptor exposes attempts, initial interval, and backoff coefficient; jitter and idempotency awareness are not documented. Retrying non-idempotent writes is a correctness hazard, not just a performance knob — this needs an explicit policy per RPC, owned by the service team, not left to defaults.
• TLS configuration is under-specified. Docs show client cert chain and private key (mutual TLS) but say nothing about CA trust roots or server name verification. This is a security review gate before any production traffic.

Key questions

1. Do we have any service that actually speaks gRPC today, or is this speculative? If speculative, the answer is "defer," not "evaluate."
2. Are we prepared to regenerate service contracts through protoc-gen-php-grpc, or do we have existing grpc/grpc stubs we cannot move? A "no" here ends the evaluation.
3. Which runtimes must carry the PECL extension — and does that include serverless (Bref/Lambda) or managed PHP platforms where we cannot compile it?
4. Who owns the timeout budget: per-attempt or end-to-end? The interceptor ordering makes this expressible, which means someone must decide it deliberately.
5. What is our stated exit path if the package stalls pre-GA, and is the abstraction layer that makes that exit cheap included in the pilot scope?
6. Does security accept mutual-TLS-only documentation, or do we require CA-root pinning that the package may not expose?

Integration Approach

Stack fit

• Best case: a Laravel or Symfony service that already runs RoadRunner or is willing to, owns its .proto files, and calls one or two upstream gRPC services. Here the standalone GrpcClient is genuinely pleasant — one create() call, interceptors via createConfig() factories, and a thin service-locator binding for framework injection.
• Worst case: a traditional PHP-FPM monolith with existing grpc/grpc-generated clients and no appetite for RoadRunner. Do not proceed; the contract-generation mismatch alone makes this a rewrite of every client call site.
• Mandatory: wrap the client behind our own narrow interface (e.g. MailSenderClient) regardless of path. The package's own API is pre-1.0; our ports must not be.

Migration path

1. Spike (3–5 eng days, one engineer): stand up the PECL extension in the CI image, generate one real service interface, and complete a round-trip against a real or stub server including TLS. Publish findings as a go/no-go memo.
2. Adapter (1 week): define our client port interfaces, implement them over GrpcClient, and centralize client construction in one factory so configuration and interceptors are not scattered across call sites.
3. Shadow pilot (2–3 weeks): run one non-critical read-only upstream through the new client behind a feature flag, mirroring or comparing against the existing path. Collect latency, error rates, and retry behavior.
4. Broaden: expand to write paths only after retry/idempotency policy is codified per RPC.

Compatibility

• PHP version must satisfy both the package constraint and a PECL grpc build; verify the extension ships for our target PHP minor before the spike, since this is the classic late-breaking blocker.
• Interceptor compatibility is a design constraint, not a checkbox: ExecuteServiceInterceptors must be positioned deliberately in the chain, and interceptor order determines whether timeouts apply per-attempt or in aggregate. Encode the chosen policy in the adapter, not in per-service config files.
• Framework version coupling for Spiral users is effectively dictated by roadrunner-bridge; treat the bridge as the versioning boundary and upgrade them together.

Sequencing

Extension availability and proto generation come first because they are binary gates. Adapter abstraction comes second because it is the exit option. Pilot comes third because it is where retry, TLS, and observability assumptions get falsified. Nothing touches a write path until the retry policy has an owner and a documented idempotency stance.

Operational Impact

Maintenance

• Low code-maintenance surface, moderate upgrade surface. Our own code is a factory plus a handful of interceptors. The risk is version churn: pre-1.0 means pinning exact versions and reading every changelog. Budget roughly one upgrade-and-retest cycle per quarter while the project is in RC.
• Two upgrade axes, not one: the Composer package and the PECL extension version must stay compatible with each other and with PHP. Add both to the dependency-review checklist; forgetting the extension side is the predictable failure.
• Interceptor code is our code. Timeout, retry, auth, tracing, and connection-rotation wiring will be ours to own, test, and document. Estimate this as a small but permanent line item, not a one-time setup cost.

Support

• No commercial support, no vendor SLA. Recourse is GitHub issues and MIT-licensed source. Given the vendor's commercial interest in RoadRunner and its own maintenance activity through 2026-03, response times are likely reasonable, but that is an expectation, not a commitment.
• Internal ownership must be explicit. Name a single technical owner for the gRPC client layer. With 40 stars there is no community well to draw from — if that person leaves, we are reading source.
• Documentation is good but uneven: DTOs, interceptor ordering, and standalone usage are well covered; exception taxonomy, CA/trust-root configuration, and retry jitter/idempotency semantics are not. Our internal runbook must fill those gaps or they will be rediscovered during an incident.

Scaling

• Multi-connection support is the strongest scaling lever: pass an array of addresses and use ConnectionsRotationInterceptor to distribute load or fail over. Adequate for typical internal service meshes; not a substitute for proper service-side load balancing or a sidecar.
• Long-running worker friendliness is a real advantage. Interceptors are recreated per request and scoped to the calling container scope, so stateful per-call concerns (auth tokens, trace context, deadlines) are safe in RoadRunner's resident-worker model — a common footgun in other long-running PHP clients.
• PHP-FPM will pay connection setup cost per request. Connection reuse is a function of worker lifecycle; if the bulk of our fleet is FPM, throughput assumptions inherited from RoadRunner benchmarks will not hold. Model this before committing to latency SLOs.

Failure modes

• Extension missing or version-mismatched at deploy: hard failure at boot, not at first call. Mitigate with a startup health check and a build-time assertion.
• Ambiguous timeout budget: if timeouts are layered without an explicit policy, retries can extend total call duration well past caller expectations, cascading into upstream timeouts under load. This is the most likely production incident and the cheapest to prevent — define the budget, write a conformance test.
• Retry amplification on non-idempotent RPCs: duplicate writes. Requires per-RPC policy, documented and reviewed.
• TLS misconfiguration: the docs cover client certs but not CA trust roots, so a permissive or incorrect verification setup is a plausible default. Security review before pilot traffic.
• Silent degradation on failover: connection rotation may mask a persistently failing endpoint until redundancy is exhausted. Needs per-endpoint health visibility, which we must build.
• No native tracing: a stalled call is indistinguishable from a slow upstream without our own instrumentation. Build the tracing interceptor during the pilot, not after.

Ramp-up

• Days for a Spiral/RoadRunner developer, because the idioms are already familiar and roadrunner-bridge handles wiring.
• One to two weeks for a Laravel-focused team to be productive with the standalone client, plus additional time for the protoc-gen-php-grpc toolchain and the DTO config model if per-service interceptors are needed.
• The real ramp-up cost is organizational, not individual: platform must own the extension in every image, security must bless the TLS story, and each service team must own its retry/idempotency policy. Plan a half-day enablement session plus a written runbook, and treat the adapter interface as the teaching artifact.

Recommendation: position as Evaluate, not Adopt — conditional go if we are on Spiral/RoadRunner with gRPC already in play, defer if we are a PHP-FPM shop with no current gRPC traffic. Gate production on four artifacts: working extension in CI, CA trust-root confirmation from security, a written timeout/retry policy per RPC, and a merged adapter layer that makes swapping the transport a one-file change.