Weave Code
Gax Laravel Package
google/gax
Google API Core for PHP (gax-php) provides shared infrastructure for Google API clients, especially generated libraries using gRPC. Includes helpers for retries, pagination/page streaming, long-running operations, and Google API conventions. Requires PHP 8.1+.
Google API Core for PHP (google/gax) provides the foundational runtime used by generated Google Cloud PHP clients. It implements common Google API conventions on top of gRPC, enabling higher-level client libraries to offer consistent, idiomatic behaviors without requiring most applications to interact with GAX directly.
Designed for PHP 8.1+ and maintained under Semantic Versioning (GA), it powers features like pagination, retries, and long‑running operations across generated SDKs.
- gRPC transport support aligned with Google API patterns
- Built-in retry and timeout configuration helpers
- Page streaming utilities for paginated RPCs
- Long-running operations client support
- Shared protobuf/common type scaffolding for generated libraries
Frequently asked questions about Gax
- Can I use google/gax in a Laravel app without knowing gRPC or protobuf?
- While the package abstracts gRPC complexity, you’ll still need protobuf-generated code (from .proto files) for your target Google API. Laravel teams unfamiliar with gRPC may face a learning curve, but the package simplifies client-side operations like retries and pagination once set up. Start with Google’s generated clients (e.g., `google/cloud-storage`) which rely on gax under the hood.
- How do I install google/gax in Laravel with pecl protobuf dependencies?
- First, install the protobuf extension via `pecl install protobuf` (requires PHP 8.1+). Then add `google/gax` to your `composer.json` and run `composer install`. For Laravel deployments, ensure your Dockerfile or CI/CD pipeline includes the pecl step. Shared hosting may not support pecl, so consider containerized environments like Laravel Sail or Heroku.
- Will google/gax work with Laravel’s service container for dependency injection?
- Yes. Register gRPC clients as Laravel services in `AppServiceProvider` using the container’s `singleton()` method. For example, bind `StorageClient` with credentials and endpoints from config. The package’s `GapicClientTrait` and `ClientOptionsTrait` support configurable retry policies, logging, and other options via constructor injection.
- Does google/gax support Laravel’s middleware for gRPC calls?
- Indirectly. Use `TransportCallMiddleware` or `prependMiddleware()` on gRPC clients to intercept calls (e.g., for auth, logging, or metrics). For HTTP-gRPC bridging, create a Laravel middleware that delegates to the gRPC client. Example: Log gRPC errors via `ApiException` and convert them to Laravel’s `HttpException` in a middleware.
- What Laravel versions are compatible with google/gax?
- The package itself requires PHP 8.1+, but Laravel compatibility depends on your Google Cloud client (e.g., `google/cloud-storage` for v1.0+). Test with Laravel 9/10 for best results. Avoid Laravel 8.x if using newer Google API clients, as they may drop PHP 7.4 support. Check the client’s `composer.json` for Laravel-specific requirements.
- How do I handle gRPC errors (ApiException) in Laravel?
- Catch `ApiException` and map it to Laravel’s `HttpException` or a custom exception. Use `$e->getErrorDetails()` for rich error data (e.g., debug logs). Example: `throw new HttpException(500, $e->getMessage(), [], $e->getErrorDetails());`. For global handling, create an exception handler in `app/Exceptions/Handler.php` to standardize gRPC error responses.
- Can I use google/gax for async gRPC calls in Laravel?
- Laravel’s synchronous nature limits async gRPC features, but you can offload work to queues (e.g., `google/longrunning` for operations) or use ReactPHP for async streams. For example, dispatch a job to process Pub/Sub messages asynchronously. Avoid blocking HTTP requests with long-running gRPC calls; use Laravel’s queue system instead.
- Are there alternatives to google/gax for Google Cloud in Laravel?
- For REST-based Google Cloud APIs, use `google/cloud-*` clients (e.g., `google/cloud-storage`), which internally use gax but expose a simpler HTTP interface. If you need gRPC, alternatives are limited—most Google Cloud APIs require gRPC for advanced features like streaming. For non-Google gRPC, consider `grpc/grpc` or `reactphp/grpc`, but they lack Google API conventions.
- How do I configure retry policies for gRPC calls in Laravel?
- Use `ClientOptionsTrait` to set retry settings via `setRetrySettings()`. Example: `$client->setRetrySettings(new RetrySettings([new ExponentialBackoffRetry()]))`. For Laravel, bind these options in your service provider. Google’s default retry policies handle transient errors, but customize them for idempotent operations or specific backoff logic.
- Will google/gax impact Laravel’s production performance or deployment size?
- The package adds ~5MB from protobuf/gRPC dependencies, which may affect cold starts in serverless Laravel (e.g., Bref). Optimize by using Docker layers to cache dependencies or pruning unused protobuf classes. For traditional servers, the impact is minimal. Monitor deployment size and consider splitting gRPC logic into a microservice if needed.
Weaver
How can I help you explore Laravel packages today?