google-cloud-php: one Composer package per Google Cloud service, and the auth that makes them work

A monorepo where you install only the piece you need

The Google Cloud PHP client is an idiomatic PHP client for Google Cloud Platform services, and the packaging is the first thing to understand. The repository is a monorepo with one directory per service, and the listing makes the scope obvious: AccessApproval, AdsAdManager, AiPlatform, AlloyDb, ApiGateway, ArtifactRegistry, BigQuery with a long list of subdirectories for its many surfaces, Bigtable, Billing, BinaryAuthorization, and hundreds more after that.

The recommendation in the documentation is to install individual component packages rather than the whole thing, with the list available on Packagist under the google/cloud- search. The examples given are:

$ composer require google/cloud-storage
$ composer require google/cloud-bigquery
$ composer require google/cloud-datastore

So the dependency graph of a typical project is a handful of small packages, one per service you actually call. This matters more than it might sound, because a client library that bundles every service brings a large dependency tree and an upgrade surface you have to absorb whether you use the services or not.

The boundary with the rest of Google is also drawn explicitly. If you need support for other Google APIs, the documentation points you to the Google APIs Client Library for PHP instead. Google Cloud and Google APIs are different surfaces with different auth models, and this repository covers the former.

The reference documentation is at cloud.google.com/php/docs/reference, and the project is Apache-2.0 licensed with a LICENSE file at the root. The release cadence is fast, with v0.349.0 on 2026-10-07, v0.348.0 on 2026-10-05 and v0.347.0 on 2026-09-28, and the last push was on 2026-10-15. The 0.x version line reflects that the surface is still moving.

Application default credentials are what make local and production match

The authentication model is the part of this client that most affects how you develop and deploy, and it is built around application default credentials.

The documented local development path starts with installing the Google Cloud CLI, then authenticating to generate the credentials file:

$ gcloud init
$ gcloud auth application-default login

That creates a local file that the client's authentication library reads in order to make requests, and the location depends on the system. On Windows it is at %APPDATA%\gcloud\application_default_credentials.json, and on Linux and macOS it is at $HOME/.config/gcloud/application_default_credentials.json.

The point of the mechanism is that the client code does not change between a laptop and a deployed environment. The client object is constructed with an empty options array, and it detects the JSON file and uses it to authenticate the requests:

require_once 'vendor/autoload.php';

use Google\Cloud\Translate\V3\Client\TranslationServiceClient;
use Google\Cloud\Translate\V3\TranslateTextRequest;

// Instantiating the client gathers the credentials from the `application_default_credentials.json`
$client = new TranslationServiceClient([]);

$request = new TranslateTextRequest();
$request->setParent('projects/<YOUR_PROJECT_ID>');
$request->setTargetLanguageCode('en-US');
$request->setContents(['こんにちは']);

$response = $client->translateText($request);

The shape of the API is consistent across services. A request object is built with setters, a method on the client takes the request, and the response is a protobuf message you read with getters. The V3 namespace on the client class, Google\Cloud\Translate\V3\Client\TranslationServiceClient, tells you these are generated clients tied to a specific API version.

On a deployed host the same mechanism resolves through the platform credential source rather than the local file, which is the standard arrangement, and the AUTHENTICATION.md document in the repository covers the details and examples for each case.

gRPC or REST, and the extension requirement that decides it

Many clients in Google Cloud PHP offer support for gRPC, either as an option or as a requirement, and gRPC is a high-performance RPC framework created by Google.

To use gRPC in PHP you must install the gRPC PHP extension on your server, and the protobuf extension is recommended in production even though it is not required:

$ pecl install grpc
$ pecl install protobuf

The distinction between option and requirement varies by client, and that is the practical problem. A service whose API is gRPC only, or whose client is generated without a REST transport, forces the extension onto your infrastructure. Others will work over REST but you are choosing the slower path. Since this repository spans hundreds of services with different API surfaces, you cannot answer the question once for the whole library, only per service.

There is also a debugging guide in the repository, DEBUG.md, covering the debugging tools, and a separate GRPC.md with the complete guide for installing the extensions.

The performance difference is the reason to bother, and the operational burden is the reason not to. Installing a PECL extension into your PHP build is a one-time cost on a server you control, and it is a recurring cost if you run PHP in a container that gets rebuilt, or on a managed host where you do not control the extension set. A team that deploys to a platform with a fixed PHP build has less room here than a team with its own images.

Caching access tokens across processes

By default the library uses a simple in-memory caching implementation for access tokens, and the documentation explains how to override it by passing a PSR-6 cache implementation into the desired client.

The example uses the Symfony Cache component:

require 'vendor/autoload.php';

use Google\Cloud\Storage\StorageClient;
use Symfony\Component\Cache\Adapter\ArrayAdapter;

// Please take the proper precautions when storing your access tokens in a cache no matter the implementation.
$cache = new ArrayAdapter();

$storage = new StorageClient([
    'authCache' => $cache
]);

The comment in that snippet is the important part. Access tokens are credentials, and the default in-memory cache keeps them in the process, which is safe. The moment you move them into a shared cache, you have moved credentials into something other processes can read, and the precaution comment is there to say so.

The library ships its own PSR-6 implementation backed by SystemV shared memory, at Google\Auth\Cache\SysVCacheItemPool:

require __DIR__ . '/vendor/autoload.php';

use Google\Cloud\Spanner\SpannerClient;
use Google\Auth\Cache\SysVCacheItemPool;

$cache = new SysVCacheItemPool();

$spanner = new SpannerClient([
    'authCache' => $cache
]);

This one is only available on nix machines, and the documentation describes it as one of the fastest implementations, with the property that you can share the cache among multiple processes.

That last property is the reason to care. A PHP-FPM setup runs several worker processes, and with an in-memory cache each worker obtains its own token, which means each one pays the token exchange cost. A shared cache means one exchange serves the pool, and on a busy service the difference is a measurable number of authentication round trips per minute. The trade is that a shared cache needs appropriate permissions and locking, and it needs to be treated as a credential store.

Post-quantum key exchange, and the version checks it needs

The client libraries support post-quantum key exchange using the X25519MLKEM768 hybrid mechanism for TLS 1.3 connections, as part of Google Cloud's rollout of post-quantum cryptography across its services to protect against the Store Now, Decrypt Later attack.

The implementation details differ by transport, and this is where a team can quietly end up without post-quantum protection while believing it has it.

Over gRPC, the grpc PHP extension statically bundles BoringSSL, and beginning with grpc v1.83.0, BoringSSL natively supports and advertises the X25519MLKEM768 hybrid group by default during TLS 1.3 handshakes. The configuration requirement is pleasingly simple: no code changes, compilation flags, or environment variables are required. The verification is a version check:

php -r "echo phpversion('grpc') . PHP_EOL;"

And there is a fallback: if connecting to an endpoint that does not support PQC, the handshake automatically falls back to classical X25519.

Over the REST transport with Guzzle and cURL, the negotiation relies on the host system's OpenSSL library as linked to PHP's curl extension. The requirement is OpenSSL 3.5.0 or higher, since that version introduced native support for X25519MLKEM768 and enabled it by default in the TLS 1.3 supported groups. The verification here is a different command, checking the SSL library PHP's curl extension is actually linked against:

php -r "echo curl_version()['ssl_version'] . PHP_EOL;"

That check is worth running rather than assuming. A host can have OpenSSL 3.5 installed and still have PHP's curl extension linked to an older system default, and the version check is what catches it. Guzzle inherits the default curve preferences from the underlying TLS library, so X25519MLKEM768 is preferred automatically when OpenSSL 3.5 or later is present, with a fallback to the classical curve otherwise.

Editorial conclusion

google-cloud-php suits a PHP team that already runs on Google Cloud and wants a supported client for a specific service without taking a dependency on the whole platform surface, and it suits teams moving between local development and a deployed environment because the same client code authenticates through application default credentials in both. It is a poor fit if you need the non-Google APIs, since those live in a separate client library, and a poor fit if you cannot run the gRPC extension, since many clients need it or strongly prefer it. Before adopting, check whether the service you need has a component package at all, decide whether the gRPC or the REST transport suits your host, and read the post-quantum section, because hybrid key exchange needs grpc 1.83.0 or OpenSSL 3.5 depending on the transport you pick.

Frequently asked questions

Official sources

1. googleapis/google-cloud-php on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases