Download the PHP package thesis/grpc-client without Composer

thesis/grpc-client

Read-only subtree split from https://github.com/thesis-php/grpc.

Do not open issues/PRs here. Use the monorepo:

• https://github.com/thesis-php/grpc/issues
• https://github.com/thesis-php/grpc/pulls

Async gRPC client for PHP with HTTP/2 transport, streaming RPCs, interceptors, TLS/mTLS, and client-side load balancing.

Contents

• Installation
• Requirements
• Basic usage
• TLS and mTLS
• Target addressing
• Load balancing
• Endpoint resolution
• Error handling
• Compression
• Interceptors
• Client streaming
• Server streaming
• Bidirectional streaming
• Closing the client

Installation

Requirements

To generate gRPC client classes from .proto, use:

• https://github.com/thesis-php/protoc-plugin

Basic usage

You can pass request metadata too:

TLS and mTLS

Target addressing

The target string passed to withHost() follows gRPC name resolution format: scheme:endpoint.

Supported schemes:

If scheme is omitted, dns is assumed:

Use custom DNS server with authority:

Multi-endpoint target without DNS:

Load balancing

When resolution returns multiple addresses, the load balancer picks endpoint per RPC.

Built-in policies:

• PickFirstFactory (default): shuffles endpoint list, picks one, and keeps it pinned until it disappears after refresh.
• RoundRobinFactory: cycles through all available endpoints.

With DNS targets, resolver can re-resolve by TTL and call balancer refresh() with updated endpoints. Re-resolution interval is clamped between minimum and maximum bounds (default 30..300 seconds).

Custom load balancer example:

Endpoint resolution

Resolver is selected by target scheme. You can override the resolver for a scheme:

Default resolvers by scheme:

• dns -> DnsResolver
• ipv4, ipv6, unix -> StaticResolver
• passthrough -> PassthroughResolver

Custom schemes (service discovery)

Register a resolver under any scheme to plug in a service registry such as etcd or Consul. The target is then <scheme>://[authority]/<endpoint>, and the endpoint is handed to the resolver as $target->opaque:

An EndpointResolver returns the current Resolution and may push updates over time through EndpointResolverListener::onResolve(), which the balancer picks up live.

Error handling

Compression

Compression reduces payload size and is useful for large protobuf messages or bandwidth-constrained links.

Interceptors

Interceptors let you add cross-cutting logic (auth, logging, tracing, metadata enrichment) without changing service stubs. Mirroring gRPC, they come in two flavours, registered on separate chains:

• UnaryInterceptor wraps a whole unary request → response call (via withUnaryInterceptors()). A retry policy, for instance, is naturally a unary interceptor — re-invoking $invoker reuses the call's pick context, so the transport fails over to another endpoint automatically.
• StreamInterceptor wraps the creation of a stream (via withStreamInterceptors()), and so also covers the underlying stream of every streaming RPC.

A unary call does not run the stream chain and vice versa. An interceptor that must apply to both (e.g. auth) implements both interfaces and is registered on both chains.

Client streaming

Use client streaming when you need to send many messages and receive one final aggregated response.

Server streaming

Use server streaming when a single request should return a sequence of server messages.

Bidirectional streaming

Use bidirectional streaming for conversational protocols where both sides can send messages independently.

Closing the client

Call Client::close() to stop background resolver activity and release resources, especially when DNS re-resolution is enabled.