Skip to content

Latest commit

 

History

History
377 lines (291 loc) · 12.3 KB

UPGRADING.md

File metadata and controls

377 lines (291 loc) · 12.3 KB
Raw

Google API Client Upgrade Guide

2.x to 2.10.0

Namespaces

The Google API Client for PHP now uses namespaces for all classes. Code using the legacy classnames will continue to work, but it is advised to upgrade to the underspaced names, as the legacy classnames will be deprecated some time in the future.

Before

$client = new Google_Client();
$service = new Google_Service_Books($client);

After

$client = new Google\Client();
$service = new Google\Service\Books($client);

Service class constructors

Service class constructors now accept an optional Google\Client|array parameter as their first argument, rather than requiring an instance of Google\Client.

Before

$client = new Google_Client();
$client->setApplicationName("Client_Library_Examples");
$client->setDeveloperKey("YOUR_APP_KEY");

$service = new Google_Service_Books($client);

After

$service = new Google\Service\Books([
    'application_name' => "Client_Library_Examples",
    'developer_key'    => "YOUR_APP_KEY",
]);

1.0 to 2.0

The Google API Client for PHP has undergone major internal changes in 2.0. Please read through the list below in order to upgrade to the latest version:

Installation now uses Composer

Before

The project was cloned in your project and you would run the autoloader from wherever:

// the autoload file was included
require_once 'google-api-php-client/src/Google/autoload.php'; // or wherever autoload.php is located
// OR classes were added one-by-one
require_once 'Google/Client.php';
require_once 'Google/Service/YouTube.php';

After

This library now uses composer (We suggest installing composer globally). Add this library by running the following in the root of your project:

$ composer require google/apiclient:~2.0

This will install this library and generate an autoload file in vendor/autoload.php in the root of your project. You can now include this library with the following code:

require_once 'vendor/autoload.php';

Access Tokens are passed around as arrays instead of JSON strings

Before

$accessToken = $client->getAccessToken();
print_r($accessToken);
// would output:
// string(153) "{"access_token":"ya29.FAKsaByOPoddfzvKRo_LBpWWCpVTiAm4BjsvBwxtN7IgSNoUfcErBk_VPl4iAiE1ntb_","token_type":"Bearer","expires_in":3593,"created":1445548590}"
file_put_contents($credentialsPath, $accessToken);

After

$accessToken = $client->getAccessToken();
print_r($accessToken);
// will output:
// array(4) {
//   ["access_token"]=>
//   string(73) "ya29.FAKsaByOPoddfzvKRo_LBpWWCpVTiAm4BjsvBwxtN7IgSNoUfcErBk_VPl4iAiE1ntb_"
//   ["token_type"]=>
//   string(6) "Bearer"
//   ["expires_in"]=>
//   int(3593)
//   ["created"]=>
//   int(1445548590)
// }
file_put_contents($credentialsPath, json_encode($accessToken));

ID Token data is returned as an array

Before

$ticket = $client->verifyIdToken($idToken);
$data = $ticket->getAttributes();
$userId = $data['payload']['sub'];

After

$userData = $client->verifyIdToken($idToken);
$userId = $userData['sub'];

Google_Auth_AssertionCredentials has been removed

For service accounts, we now use setAuthConfig or useApplicationDefaultCredentials

Before

$client_email = '[email protected]';
$private_key = file_get_contents('MyProject.p12');
$scopes = array('https://www.googleapis.com/auth/sqlservice.admin');
$credentials = new Google_Auth_AssertionCredentials(
    $client_email,
    $scopes,
    $private_key
);

After

$client->setAuthConfig('/path/to/service-account.json');

// OR use environment variables (recommended)

putenv('GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json');
$client->useApplicationDefaultCredentials();

Note: P12s are deprecated in favor of service account JSON, which can be generated in the Credentials section of Google Developer Console.

In order to impersonate a user, call setSubject when your service account credentials are being used.

Before

$user_to_impersonate = '[email protected]';
$credentials = new Google_Auth_AssertionCredentials(
    $client_email,
    $scopes,
    $private_key,
    'notasecret',                                 // Default P12 password
    'http://oauth.net/grant_type/jwt/1.0/bearer', // Default grant type
    $user_to_impersonate,
);

After

$user_to_impersonate = '[email protected]';
$client->setSubject($user_to_impersonate);

Additionally, Google_Client::loadServiceAccountJson has been removed in favor of Google_Client::setAuthConfig:

Before

$scopes = [ Google_Service_Books::BOOKS ];
$client->loadServiceAccountJson('/path/to/service-account.json', $scopes);

After

$scopes = [ Google_Service_Books::BOOKS ];
$client->setAuthConfig('/path/to/service-account.json');
$client->setScopes($scopes);

Google_Auth_AppIdentity has been removed

For App Engine authentication, we now use the underlying google/auth and call useApplicationDefaultCredentials:

Before

$client->setAuth(new Google_Auth_AppIdentity($client));
$client->getAuth()
    ->authenticateForScope('https://www.googleapis.com/auth/sqlservice.admin')

After

$client->useApplicationDefaultCredentials();
$client->addScope('https://www.googleapis.com/auth/sqlservice.admin');

This will detect when the App Engine environment is present, and use the appropriate credentials.

Google_Auth_Abstract classes have been removed

google/auth is now used for authentication. As a result, all Google_Auth-related functionality has been removed. The methods that were a part of Google_Auth_Abstract have been moved into the Google_Client object.

Before

$request = new Google_Http_Request();
$client->getAuth()->sign($request);

After

// create an authorized HTTP client
$httpClient = $client->authorize();

// OR add authorization to an existing client
$httpClient = new GuzzleHttp\Client();
$httpClient = $client->authorize($httpClient);

Before

$request = new Google_Http_Request();
$response = $client->getAuth()->authenticatedRequest($request);

After

$httpClient = $client->authorize();
$request = new GuzzleHttp\Psr7\Request('POST', $url);
$response = $httpClient->send($request);

NOTE: $request can be any class implementing Psr\Http\Message\RequestInterface

In addition, other methods that were callable on Google_Auth_OAuth2 are now called on the Google_Client object:

Before

$client->getAuth()->refreshToken($token);
$client->getAuth()->refreshTokenWithAssertion();
$client->getAuth()->revokeToken($token);
$client->getAuth()->isAccessTokenExpired();

After

$client->refreshToken($token);
$client->refreshTokenWithAssertion();
$client->revokeToken($token);
$client->isAccessTokenExpired();

PHP 5.6 is now the minimum supported PHP version

This was previously PHP 5.2. If you still need to use PHP 5.2, please continue to use the v1-master branch.

Guzzle and PSR-7 are used for HTTP Requests

The HTTP library Guzzle is used for all HTTP Requests. By default, Guzzle 6 is used, but this library is also compatible with Guzzle 5. As a result, all Google_IO-related functionality and Google_Http-related functionality has been changed or removed.

  1. Removed Google_Http_Request
  2. Removed Google_IO_Abstract, Google_IO_Exception, Google_IO_Curl, and Google_IO_Stream
  3. Removed methods Google_Client::getIo and Google_Client::setIo
  4. Refactored Google_Http_Batch and Google_Http_MediaFileUpload for Guzzle
  5. Added Google_Client::getHttpClient and Google_Client::setHttpClient for getting and setting the Guzzle GuzzleHttp\ClientInterface object.

NOTE: PSR-7-compatible libraries can now be used with this library.

Other Changes

  • PSR 3 LoggerInterface is now supported, and Monolog is used for all logging. As a result, all Google_Logger-related functionality has been removed:
    1. Removed Google_Logger_Abstract, Google_Logger_Exception, Google_Logger_File, Google_Logger_Null, and Google_Logger_Psr
    2. Google_Client::setLogger now requires Psr\Log\LoggerInterface
  • firebase/jwt is now used for all JWT signing and verifying. As a result, the following classes have been changed or removed:
    1. Removed Google_Signer_P12
    2. Removed Google_Verifier_Pem
    3. Removed Google_Auth_LoginTicket (see below)
  • The following classes and methods have been removed in favor of google/auth:
    1. Removed methods Google_Client::getAuth and Google_Client::setAuth
    2. Removed Google_Auth_Abstract
      • Google_Auth_Abstract::sign and Google_Auth_Abstract::authenticatedRequest have been replaced by Google_Client::authorize. See the above examples for more details.
    3. Removed Google_Auth_AppIdentity. This is now supported in google/auth and is used automatically when Google_Client::useApplicationDefaultCredentials is called.
    4. Removed Google_Auth_AssertionCredentials. Use Google_Client::setAuthConfig instead.
    5. Removed Google_Auth_ComputeEngine. This is now supported in google/auth, and is used automatically when Google_Client::useApplicationDefaultCredentials is called.
    6. Removed Google_Auth_Exception
    7. Removed Google_Auth_LoginTicket. Calls to Google_Client::verifyIdToken now returns the payload of the ID Token as an array if the verification is successful.
    8. Removed Google_Auth_OAuth2. This functionality is now supported in google/auth and wrapped in Google_Client. These changes will only affect applications calling Google_Client::getAuth, as the methods on Google_Client have not changed.
    9. Removed Google_Auth_Simple. This is now supported in google/auth and is used automatically when Google_Client::setDeveloperKey is called.
  • Google_Client::sign has been replaced by Google_Client::authorize. This function now takes a GuzzleHttp\ClientInterface object and uses the following decision tree for authentication:
    1. Uses Application Default Credentials when Google_Client::useApplicationDefaultCredentials is called
    • Looks for GOOGLE_APPLICATION_CREDENTIALS environment variable if set
    • Looks in ~/.config/gcloud/application_default_credentials.json
    • Otherwise, uses GCECredentials
    1. Uses API Key if set (see Client::setDeveloperKey)
    2. Uses Access Token if set (call Client::setAccessToken)
    3. Automatically refreshes access tokens if one is set and the access token is expired
  • Removed Google_Config
  • Removed Google_Utils
  • PSR-6 cache is used for all caching. As a result:
    1. Removed Google_Cache_Abstract
    2. Classes Google_Cache_Apc, Google_Cache_File, Google_Cache_Memcache, and Google_Cache_Null now implement Google\Auth\CacheInterface.
    3. Google Auth provides simple caching utilities which are used by default unless you provide alternatives.
  • Removed $boundary constructor argument for Google_Http_MediaFileUpload