This document provides all the basic information you need to start using the library. It covers important library concepts, shows examples for various use cases, and gives links to more information.
There are a few setup steps you need to complete before you can use this library:
It is important to understand the basics of how API authentication and authorization are handled. All API calls must use either simple or authorized access (defined below). Many API methods require authorized access, but some can use either. Some API methods that can use either behave differently, depending on whether you use simple or authorized access. See the API's method documentation to determine the appropriate access type.
These API calls do not access any private user data. Your application must authenticate itself as an application belonging to your Google Cloud project. This is needed to measure project usage for accounting purposes.
Warning: Keep your API key private. If someone obtains your key, they could use it to consume your quota or incur charges against your Google Cloud project.
These API calls access private user data. Before you can call them, the user that has access to the private data must grant your application access. Therefore, your application must be authenticated, the user must grant access for your application, and the user must be authenticated in order to grant that access. All of this is accomplished with OAuth 2.0 and libraries written for it.
Scope: Each API defines one or more scopes that declare a set of operations permitted. For example, an API might have read-only and read-write scopes. When your application requests access to user data, the request must include one or more scopes. The user needs to approve the scope of access your application is requesting.
Refresh and access tokens: When a user grants your application access, the OAuth 2.0 authorization server provides your application with refresh and access tokens. These tokens are only valid for the scope requested. Your application uses access tokens to authorize API calls. Access tokens expire, but refresh tokens do not. Your application can use a refresh token to acquire a new access token.
Warning: Keep refresh and access tokens private. If someone obtains your tokens, they could use them to access private user data.
Client ID and client secret: These strings uniquely identify your application and are used to acquire tokens. They are created for your Google Cloud project on the API Access pane of the Google Cloud. There are three types of client IDs, so be sure to get the correct type for your application:
Warning: Keep your client secret private. If someone obtains your client secret, they could use it to consume your quota, incur charges against your Google Cloud project, and request access to user data.
This section described how to build an API-specific service object, make calls to the service, and process the response.
The client object is the primary container for classes and configuration in the library.
$client = new Google_Client();
$client->setApplicationName("My Application");
$client->setDeveloperKey("MY_SIMPLE_API_KEY");
Services are called through queries to service specific objects. These are created by constructing the service object, and passing an instance of Google_Client to it. Google_Client contains the IO, authentication and other classes required by the service to function, and the service informs the client which scopes it uses to provide a default when authenticating a user.
$service = new Google_Service_Books($client);
Each API provides resources and methods, usually in a chain. These can be accessed from the service object in the form $service->resource->method(args). Most method require some arguments, then accept a final parameter of an array containing optional parameters. For example, with the Google Books API, we can make a call to list volumes matching a certain string, and add an optional filter parameter.
$optParams = array('filter' => 'free-ebooks');
$results = $service->volumes->listVolumes('Henry David Thoreau', $optParams);
There are two main types of response - items and collections of items. Each can be accessed either as an object or as an array. Collections implement the Iterator interface so can be used in foreach and other constructs.
foreach ($results as $item) {
echo $item['volumeInfo']['title'], "<br /> \n";
}
This library works well with Google App Engine applications. The Memcache class is automatically used for caching, and the file IO is implemented with the use of the Streams API.