Migrating From 0.6.* to 1.0.0

The change to 1.0.0 should mostly only affect application in the naming. This is now more standard and reliable.

General Migration Considerations

File naming & include paths

Class names now reflect file paths under the src/ folder, and all names are property structured. For example the class Google_Client will be in file location src/Google/Client.php. Services are under Google/Service and are named similarly, so for example the class Google_Services_Plus can be found in src/Google/Service/Plus.php.

The major change for models is that internal resources are now prefixed with their service name to avoid collisions. For example, Google_Person becomes Google_Service_Plus_Person.

In general code, you need to change the include paths and the service filenames to make sure they match the class name:

require_once 'google-api-php-client/src/Google/Client.php';
require_once 'google-api-php-client/src/contrib/Google/Service/Plus.php';
      

To

require_once 'google-api-php-client/src/Google/Client.php';
require_once 'google-api-php-client/src/Google/Service/Plus.php';
       

Files are generally explicitly included where needed. The library does not currently assume an autoloader, though would be fairly easily modified to be used with one.

No inner super global references, and simplified authentication

All scopes now need to be manually specified - the library no longer attemtps to guess based on the supplied services. All authentication calls must define scopes with the setScopes or addScope methods.

There are no internal references to $_GET any longer, so now you need to call Google_Client->authenticate with the code when performing an OAuth 2.0 token exchange:

$client->authenticate($_GET['code']);
      

You can no longer use authenticate to trigger the auth process with the built in redirect. Use createAuthUrl() to generate an authentication URL. You may also want to use the Javascript, Android or iOS client libraries to handle client side authentication.

All responses are objects

All returns from API calls are now automatically marshalled into objects. They do however include the ArrayAccess and Iterator implementations, for models and collections. This means you can address them exactly as you were previously, with the exception of some older PHP methods such as array_key_exists.

For example, in the following case we treat the objects as nested array:

$results = $service->volumes->listVolumes('Henry David Thoreau', $optParams);
foreach ($results as $item) {
  echo $item['volumeInfo']['title'], "<br /> \n";
}
      

However, both $item and $item['volumeInfo'] are objects, and can be treated as such:

foreach ($result as $item) {
  echo $item->volumeInfo->title,  "<br /> \n";
}
      

Collections implement iterators and array access. You can iterate over them or address them directly by index, as the following example demonstrates:

$yt_channels = $yt_service->channels->listChannels('contentDetails', array("mine" => true));
$likePlaylist = $yt_channels[0]->contentDetails->relatedPlaylists->likes;
      

Changes in members accessibility

The following members of Client.php have become private:

• $auth
• $io
• $cache
• $config

This means that you can no longer directly access those members; you need to use the appropriate getter instead:

$auth = $client->getAuth();
$io = $client->getIo();
$cache = $client->getCache();
$config = $client->getConfig();
      

Changes in default values

The default value for the access_type parameter of the OAuth 2.0 flow for Web Server Applications has changed from offline to online.

The default value for the approval_prompt parameter of the OAuth 2.0 flow for Web Server Applications has changed from force to auto.

A new home for authenticatedRequest

The authenticatedRequest method has been moved from the io classes to the auth classes.

Use Of Config

The library no longer uses a local config.php file for config. There are several options for configuring the client library.

Configuring with calls to the client

Google_Client exposes methods for configuring the basic parameters of the library. Authentication configuration works as before, with a couple of new methods:

setClientId()
setClientSecret()
setRedirectUri()
setApprovalPrompt()
setAccessType()
      

Access tokens methods will as before return a JSON encoded token string

getAccessToken()
setAccessToken()
      

Base objects can be set, they generally must extend Google_[Type]_Abstract, e.g. Google_Cache_Abstract.

setCache()
setAuth()
setIo()
      

Configuring with a client_secret.json

For configuring the authentication parameters, you can use the file available from the Google API Console. You can load it by calling the method setAuthConfigFile of Google_Client passing the path to the file, or by calling setAuthConfig and passing the content of the file (a JSON string).

Warning: This JSON should not be visible to external users, or your client secret may leak!

Creating a custom config ini file.

You can also configure the library using an ini file:

$client = new Google_Client("path/to/config.ini");
      

The structure of the ini file should follow the structure of the array in Config.php. Mainly it configures the class specific information:

; Test.ini file
application_name = My Test application
auth_class = Google_Auth_OAuth2
[classes]
Google_Auth_OAuth2[client_id] = 12345.apps.googleusercontent.com
Google_Auth_OAuth2[client_secret] = gjfiwnGinpena3
Google_Auth_OAuth2[redirect_uri] = http://example.com
      

It is also possible to instantiate or subclass Google_Config and pass that to the Google_Client constructor.

Simplified Large File Uploads

The method for uploading larger files has been modified. In many cases you can use it in the same way, but different approaches may benefit different conditions:

Direct File Uploads

To directly upload a file, just include the file as the data parameter of the options on a compatible method. Note that this method does not set any file metadata other than the mimetype.

$file = new Google_Service_Drive_DriveFile();
$result = $service->files->insert($file, array(
  'data' => file_get_contents(TESTFILE),
  'mimeType' => 'application/octet-stream',
  'uploadType' => 'media'
));
      

If you need to save metadata, such as a title, you can use multipart uploading:

$file = new Google_Service_Drive_DriveFile();
$file->setTitle("Hello World!");
$result2 = $service->files->insert($file, array(
  'data' => file_get_contents(TESTFILE),
  'mimeType' => 'application/octet-stream',
  'uploadType' => 'multipart'
));
      

Chunked File Upload

If the file is too large to send in a single call or you need the ability to resume the upload, you can use the resumable file upload type. This takes a little more work but allows more flexibility:

You upload the file in a series of chunks, defined by a chunksize (1MB in this case). First, construct the file meta data and set the size of the chunk:

$file = new Google_Service_Drive_DriveFile();
$file->title = "Big File";
$chunkSizeBytes = 1 * 1024 * 1024;
      

Then flag the client to defer execution of requests, and get a request for the insert.

Be sure to set setDefer back to false after the file upload if you want to make other calls after the file upload.

// Call the API with the media upload, defer so it doesn't immediately return.
$client->setDefer(true);
$request = $service->files->insert($file);
      

Create a file upload object with the file type, the request and client. Set the file size to signal to the server how much more file to expect.

// Create a media file upload to represent our upload process.
$media = new Google_Http_MediaFileUpload(
  $client,
  $request,
  'text/plain',
  null,
  true,
  $chunkSizeBytes
);
$media->setFileSize(filesize(TESTFILE));
      

Finally, read the file from disk in chunks, and send each one using the nextChunk method. The return from the call is false until the file has been fully uploaded, at which point the representation of the uploaded object is returned.

// Upload the various chunks. $status will be false until the process is
// complete.
$status = false;
$handle = fopen(TESTFILE, "rb");
while (!$status && !feof($handle)) {
  $chunk = fread($handle, $chunkSizeBytes);
  $status = $media->nextChunk($chunk);
}
       

If you want to make other calls after the file upload, set setDefer back to false:

$client->setDefer(false);
       

Google App Engine

App Engine implementation has been simplified - configuration is no longer required for the Cache and IO classes. Streams is now the default IO implementation, and the Memcache cache implementation is automatically chosen when an AppEngine environment is detected. There should be no specific configuration required to run on PHP on App Engine.