google-api-php-client: the PHP answer for APIs with no Cloud library

Maintenance mode stated in the second paragraph

The positioning paragraph appears early and it is short. The library enables you to work with Google APIs such as Gmail, Drive or YouTube on your server. Immediately after that comes the sentence that governs every other decision: these client libraries are officially supported by Google, but they are considered complete and are in maintenance mode, which the README defines as addressing critical bugs and security issues while adding no new features.

That is the same posture as the Go client, and it is stated just as plainly. Two things follow from it. You will not get a new API surface here, so if a Google product launches a method that is missing, there is no upstream path to it. And you will get security fixes, so this is not a library to be alarmed about merely because it is unchanging.

The Cloud redirection is separate and more specific. For Datastore, Cloud Storage, Pub/Sub and Compute Engine, the README recommends the Google Cloud client libraries and links to googleapis/google-cloud-php, with individual links to the datastore, pubsub, storage and compute packages. The instruction at the very top is to check that list first, before installing anything from here, because those are described as the recommended libraries.

So the decision procedure is short: look for a Cloud package, and if there is one, use it. This repository is the answer for everything else.

Composer install, and the autoloader line people forget

The requirement is PHP 8.0 or higher, which is a hard floor and worth checking before anything else. Installation has two documented paths, and Composer is called the preferred method.

composer require google/apiclient

There is a note about timeouts that turns out to be about this library's dependency tree rather than about your network. If you hit a timeout error, the README offers two fixes: raise Composer's timeout with the `COMPOSER_PROCESS_TIMEOUT=600 composer install` environment flag, or put the same value in the config section of your composer schema.

{
    "config": {
        "process-timeout": 600
    }
}

Then the line that appears in every example and is the reason a fresh clone seems to do nothing. The autoloader has to be included explicitly.

require_once '/path/to/your-project/vendor/autoload.php';

If you are not using Composer, the alternative is downloading a release zip named `google-api-php-client-[RELEASE_NAME].zip`, which the README says contains the library and its dependencies. Uncompressing it gives you the same autoloader under a different path. This is a genuinely useful escape route, since it means a shared hosting environment with no shell access is not a blocker.

The services package is not pinned, and that is deliberate

This is the most operationally important paragraph in the README and it is easy to miss because it is written as a rationale rather than a warning. The library relies on `google/apiclient-services`, which provides up-to-date API wrappers for a large number of Google APIs. So that users can make use of the latest API clients, this library does not pin to a specific version of that package.

Not pinning means a fresh install picks up whatever the current service wrappers are. The README then recommends that you pin to the latest version yourself before using the library in production, specifically to prevent the accidental installation of API wrappers with breaking changes.

That is a fair trade and a reasonable instruction, but it means the upgrade path is yours to manage. A deployment that runs `composer update` without constraints can change generated wrapper behaviour under you, and nothing in the main library version number will tell you it happened.

There is a related consequence for image size, which the README addresses next. There are over 200 Google API services, and the chances are good you do not want all of them shipped with your code. A Composer task handles this, and you declare which services to keep in your `composer.json`.

Cutting two hundred services down to the two you use

The cleanup task is wired into Composer's own lifecycle, which is what makes it effective. You add the task as a `pre-autoload-dump` script, which Composer runs before it regenerates the autoloader, so the removal happens on every install and every update.

{
    "require": {
        "google/apiclient": "^2.15.0"
    },
    "scripts": {
        "pre-autoload-dump": "Google\\Task\\Composer::cleanup"
    },
    "extra": {
        "google/apiclient-services": [
            "Drive",
            "YouTube"
        ]
    }
}

Running `composer update`, or a fresh `composer install`, then removes every service other than Drive and YouTube. The namespace is `Google\Task\Composer::cleanup`, and the class name is not namespaced per service, which is a hint that this is a task registered with Composer rather than an ordinary class.

The README is unusually clear about the failure mode. If you add services back into `composer.json`, you need to remove the `vendor/google/apiclient-services` directory explicitly for the change to take effect.

rm -r vendor/google/apiclient-services
composer update

There is a second gotcha in the same area. The service name matching is exact, so keeping YouTube does not keep YouTubeReporting or YouTubeAnalytics, and those have to be listed individually.

{
    "extra": {
        "google/apiclient-services": [
            "Drive",
            "YouTube",
            "YouTubeAnalytics",
            "YouTubeReporting"
        ]
    }
}

For a PHP application on shared hosting or a small container, this is the difference between a few megabytes of dependencies and a few hundred.

The basic example is three objects and one method call

The API surface is a client, a service class and a method on the service that reads like a REST path. That last property is the thing that makes these generated clients pleasant to use in PHP, where there is no static typing to lean on.

// include your composer dependencies
require_once 'vendor/autoload.php';

$client = new Google\Client();
$client->setApplicationName("Client_Library_Examples");
$client->setDeveloperKey("YOUR_APP_KEY");

$service = new Google\Service\Books($client);
$query = 'Henry David Thoreau';
$optParams = [
  'filter' => 'free-ebooks',
];
$results = $service->volumes->listVolumes($query, $optParams);

`$service->volumes` is a collection object and `listVolumes` is the API method, so the code reads the way the HTTP request does. `setApplicationName` and `setDeveloperKey` are the two calls needed for a key-authenticated call, and the developer key is the one that shows up in query parameters rather than a header.

Response objects behave like arrays, which is the other reason this style works in PHP. The README's example iterates the results and reaches into nested keys directly.

foreach ($results->getItems() as $item) {
  echo $item['volumeInfo']['title'], "<br /> \n";
}

There is a trade in that convenience. Array access on a response object means a renamed field in the API surfaces as an undefined index notice rather than a compile error, so static analysis is worth wiring up. The repository carries a `phpstan.neon.dist` and a `phpcs.xml.dist`, which suggests the project itself is analysed rather than merely shipped.

OAuth for web applications, in five documented steps

The authentication section is laid out as numbered steps, and following it literally is the advice. First, follow the instructions for creating web application credentials. Second, download the JSON credentials. Third, point the client at that file.

$client = new Google\Client();
$client->setAuthConfig('/path/to/client_credentials.json');

Fourth, declare the scopes the API requires, using the constant on the service class so a typo becomes a fatal error rather than a rejected request.

$client->addScope(Google\Service\Drive::DRIVE);

Fifth, set the redirect URI. The README's example redirects back to the same page, building it from the request.

// Your redirect URI can be any registered URI, but in this example
// we redirect back to this same page
$redirect_uri = 'http://' . $_SERVER['HTTP_HOST'] . $_SERVER['PHP_SELF'];
$client->setRedirectUri($redirect_uri);

Then, in the script that handles the redirect, exchange the authorization code for an access token. The README begins that snippet by checking for the `code` query parameter.

The redirect URI has to match what you registered, and building it from the request host is fine in development and a bad idea in production behind a proxy, where the host header may not be what you registered. Set it to a fixed string in that case.

The examples directory covers the rest of the surface: batch requests, ID tokens, large file downloads and uploads, service accounts, multi-API access and a simple query, each as a standalone file. There is also a development server command for browsing them.

$ php -S localhost:8000 -t examples/

Since the files are plain PHP rather than a framework application, running them is the fastest way to see the OAuth flow end to end before wiring it into your own routing.

Editorial conclusion

This library is a good fit for exactly one situation, and that situation is common enough. You have a PHP application, it needs to talk to a Google API with no dedicated Cloud library, and you would rather not implement OAuth yourself. Inside that boundary it is well made, with service-level installation trimming hundreds of unused dependencies out of your vendor directory and a clear OAuth flow documented step by step. Outside that boundary the maintenance mode notice applies, so treat new API surfaces as something you may have to add yourself. Install with Composer rather than the zip, run the cleanup task, pin `google/apiclient-services` before production, and keep an eye on UPGRADING.md when you bump the major version.

Frequently asked questions

Official sources

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