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).
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.
// 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.