Weave Code
Grpc Client Laravel Package
spiral/grpc-client
Lightweight, extensible PHP gRPC client with a Guzzle-like API. Supports standalone use or Spiral integration, configurable via DTOs, includes interceptors (timeouts, retries), and rich exceptions for error handling. Requires the PHP gRPC extension.
spiral/grpc-client is a lightweight, framework-friendly gRPC client for PHP that offers a clean, Guzzle-like API for calling generated service stubs. It supports both Spiral integration (via a bootloader) and standalone usage with simple configuration and extensibility.
Key features:
- Simple client API: create a client, resolve a service interface, call methods directly
- Interceptor pipeline for cross-cutting concerns (e.g., timeouts, retries)
- Config DTOs/factories for convenient, typed setup
- Robust error handling via dedicated exception types
- Works across environments (requires the PHP gRPC extension)
Frequently asked questions about Grpc Client
- Can I use spiral/grpc-client in Laravel without Spiral Framework?
- Yes, the package supports standalone usage. You can create a `GrpcClient` instance directly and bind it to Laravel’s service container manually. The Guzzle-like API works independently of Spiral, so integration is straightforward.
- What Laravel versions does spiral/grpc-client support?
- The package itself has no Laravel-specific dependencies, but it requires PHP 8.0+. For Laravel integration, ensure compatibility with your Laravel version (e.g., 8.x, 9.x, or 10.x) by manually binding the client to the container.
- How do I handle gRPC errors in Laravel’s exception handler?
- The package provides dedicated exception types (e.g., `GrpcException`). Map them to Laravel’s `Handler` by catching these exceptions and converting them to HTTP responses or logging them. Example: `catch (GrpcException $e) { return response()->json(['error' => $e->getMessage()], 500); }`
- Do I need to generate .proto files for every gRPC service?
- Yes, gRPC requires `.proto` files for service definitions. Use `protoc` to generate PHP stubs from these files. The package assumes you’ve already generated the service interfaces (e.g., `MailSenderInterface`) via `protoc --php_out=. your_service.proto`.
- How do I add authentication (e.g., JWT) to gRPC calls in Laravel?
- Use the interceptor pipeline to add auth logic. Create a custom interceptor (e.g., `JwtInterceptor`) that injects metadata or credentials into the gRPC context. Attach it via `$client->withInterceptors([new JwtInterceptor()])`.
- Will this work in Docker or shared hosting environments?
- The PHP gRPC extension must be installed, which may require custom Docker images or PECL setup. Shared hosting often lacks PECL support, so test compatibility early. Use `extension_loaded('grpc')` to verify during runtime.
- Can I use spiral/grpc-client for real-time updates (e.g., WebSocket alternatives)?
- Yes, leverage gRPC’s server-side streaming to push real-time data. Combine it with Laravel Echo or custom event handlers. Example: `$stream = $client->service(StreamService::class)->subscribe($ctx); foreach ($stream as $response) { // Handle updates }`
- How do I configure TLS/SSL for secure gRPC connections in Laravel?
- Use the `TlsConfig` DTO to define certificate paths and CA roots. Example: `$client = GrpcClient::create('grpc.example.com:443', TlsConfig::create()->withCertFile('/path/to/cert.pem')->withKeyFile('/path/to/key.pem'));`
- Are there alternatives to spiral/grpc-client for Laravel?
- For Laravel, consider `grpc/grpc` (low-level PHP gRPC) or `guzzlehttp/guzzle` (for REST). If you need a higher-level client, `spiral/grpc-client` is the most Laravel-friendly option, but it requires manual setup vs. REST’s built-in HTTP client.
- How do I test gRPC calls in Laravel’s PHPUnit?
- Mock the `GrpcClient` or use in-memory gRPC servers (e.g., `grpc_php_testing`). Example: `$mockClient = $this->createMock(GrpcClient::class); $mockClient->method('service')->willReturn($mockService); $this->app->instance(GrpcClient::class, $mockClient);`
Weaver
How can I help you explore Laravel packages today?