1Google API Client Upgrade Guide 2=============================== 3 41.0 to 2.0 5---------- 6 7The Google API Client for PHP has undergone major internal changes in `2.0`. Please read through 8the list below in order to upgrade to the latest version: 9 10## Installation now uses `Composer` 11 12**Before** 13 14The project was cloned in your project and you would run the autoloader from wherever: 15 16```php 17// the autoload file was included 18require_once 'google-api-php-client/src/Google/autoload.php'; // or wherever autoload.php is located 19// OR classes were added one-by-one 20require_once 'Google/Client.php'; 21require_once 'Google/Service/YouTube.php'; 22``` 23 24**After** 25 26This library now uses [composer](https://getcomposer.org) (We suggest installing 27composer [globally](http://symfony.com/doc/current/cookbook/composer.html)). Add this library by 28running the following in the root of your project: 29 30``` 31$ composer require google/apiclient:~2.0 32``` 33 34This will install this library and generate an autoload file in `vendor/autoload.php` in the root 35of your project. You can now include this library with the following code: 36 37```php 38require_once 'vendor/autoload.php'; 39``` 40 41## Access Tokens are passed around as arrays instead of JSON strings 42 43**Before** 44 45```php 46$accessToken = $client->getAccessToken(); 47print_r($accessToken); 48// would output: 49// string(153) "{"access_token":"ya29.FAKsaByOPoddfzvKRo_LBpWWCpVTiAm4BjsvBwxtN7IgSNoUfcErBk_VPl4iAiE1ntb_","token_type":"Bearer","expires_in":3593,"created":1445548590}" 50file_put_contents($credentialsPath, $accessToken); 51``` 52 53**After** 54 55```php 56$accessToken = $client->getAccessToken(); 57print_r($accessToken); 58// will output: 59// array(4) { 60// ["access_token"]=> 61// string(73) "ya29.FAKsaByOPoddfzvKRo_LBpWWCpVTiAm4BjsvBwxtN7IgSNoUfcErBk_VPl4iAiE1ntb_" 62// ["token_type"]=> 63// string(6) "Bearer" 64// ["expires_in"]=> 65// int(3593) 66// ["created"]=> 67// int(1445548590) 68// } 69file_put_contents($credentialsPath, json_encode($accessToken)); 70``` 71 72## ID Token data is returned as an array 73 74**Before** 75 76```php 77$ticket = $client->verifyIdToken($idToken); 78$data = $ticket->getAttributes(); 79$userId = $data['payload']['sub']; 80``` 81 82**After** 83 84```php 85$userData = $client->verifyIdToken($idToken); 86$userId = $userData['sub']; 87``` 88 89## `Google_Auth_AssertionCredentials` has been removed 90 91For service accounts, we now use `setAuthConfig` or `useApplicationDefaultCredentials` 92 93**Before** 94 95```php 96$client_email = '1234567890-a1b2c3d4e5f6g7h8i@developer.gserviceaccount.com'; 97$private_key = file_get_contents('MyProject.p12'); 98$scopes = array('https://www.googleapis.com/auth/sqlservice.admin'); 99$credentials = new Google_Auth_AssertionCredentials( 100 $client_email, 101 $scopes, 102 $private_key 103); 104``` 105 106**After** 107 108```php 109$client->setAuthConfig('/path/to/service-account.json'); 110 111// OR use environment variables (recommended) 112 113putenv('GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json'); 114$client->useApplicationDefaultCredentials(); 115``` 116 117> Note: P12s are deprecated in favor of service account JSON, which can be generated in the 118> Credentials section of Google Developer Console. 119 120In order to impersonate a user, call `setSubject` when your service account 121credentials are being used. 122 123**Before** 124 125```php 126$user_to_impersonate = 'user@example.org'; 127$credentials = new Google_Auth_AssertionCredentials( 128 $client_email, 129 $scopes, 130 $private_key, 131 'notasecret', // Default P12 password 132 'http://oauth.net/grant_type/jwt/1.0/bearer', // Default grant type 133 $user_to_impersonate, 134); 135``` 136 137**After** 138 139```php 140$user_to_impersonate = 'user@example.org'; 141$client->setSubject($user_to_impersonate); 142``` 143 144Additionally, `Google_Client::loadServiceAccountJson` has been removed in favor 145of `Google_Client::setAuthConfig`: 146 147**Before** 148 149```php 150$scopes = [ Google_Service_Books::BOOKS ]; 151$client->loadServiceAccountJson('/path/to/service-account.json', $scopes); 152``` 153 154**After** 155 156```php 157$scopes = [ Google_Service_Books::BOOKS ]; 158$client->setAuthConfig('/path/to/service-account.json'); 159$client->setScopes($scopes); 160``` 161 162## `Google_Auth_AppIdentity` has been removed 163 164For App Engine authentication, we now use the underlying [`google/auth`][Google Auth] and 165call `useApplicationDefaultCredentials`: 166 167**Before** 168 169```php 170$client->setAuth(new Google_Auth_AppIdentity($client)); 171$client->getAuth() 172 ->authenticateForScope('https://www.googleapis.com/auth/sqlservice.admin') 173``` 174 175**After** 176 177```php 178$client->useApplicationDefaultCredentials(); 179$client->addScope('https://www.googleapis.com/auth/sqlservice.admin'); 180``` 181 182This will detect when the App Engine environment is present, and use the appropriate credentials. 183 184## `Google_Auth_Abstract` classes have been removed 185 186[`google/auth`][Google Auth] is now used for authentication. As a result, all 187`Google_Auth`-related functionality has been removed. The methods that were a part of 188`Google_Auth_Abstract` have been moved into the `Google_Client` object. 189 190**Before** 191 192```php 193$request = new Google_Http_Request(); 194$client->getAuth()->sign($request); 195``` 196 197**After** 198 199```php 200// create an authorized HTTP client 201$httpClient = $client->authorize(); 202 203// OR add authorization to an existing client 204$httpClient = new GuzzleHttp\Client(); 205$httpClient = $client->authorize($httpClient); 206``` 207 208**Before** 209 210```php 211$request = new Google_Http_Request(); 212$response = $client->getAuth()->authenticatedRequest($request); 213``` 214 215**After** 216 217```php 218$httpClient = $client->authorize(); 219$request = new GuzzleHttp\Psr7\Request('POST', $url); 220$response = $httpClient->send($request); 221``` 222 223> NOTE: `$request` can be any class implementing 224> `Psr\Http\Message\RequestInterface` 225 226In addition, other methods that were callable on `Google_Auth_OAuth2` are now called 227on the `Google_Client` object: 228 229**Before** 230 231```php 232$client->getAuth()->refreshToken($token); 233$client->getAuth()->refreshTokenWithAssertion(); 234$client->getAuth()->revokeToken($token); 235$client->getAuth()->isAccessTokenExpired(); 236``` 237 238**After** 239 240```php 241$client->refreshToken($token); 242$client->refreshTokenWithAssertion(); 243$client->revokeToken($token); 244$client->isAccessTokenExpired(); 245``` 246 247## PHP 5.4 is now the minimum supported PHP version 248 249This was previously `PHP 5.2`. If you still need to use PHP 5.2, please continue to use 250the [v1-master](https://github.com/google/google-api-php-client/tree/v1-master) branch. 251 252## Guzzle and PSR-7 are used for HTTP Requests 253 254The HTTP library Guzzle is used for all HTTP Requests. By default, [`Guzzle 6`][Guzzle 6] 255is used, but this library is also compatible with [`Guzzle 5`][Guzzle 5]. As a result, 256all `Google_IO`-related functionality and `Google_Http`-related functionality has been 257changed or removed. 258 2591. Removed `Google_Http_Request` 2601. Removed `Google_IO_Abstract`, `Google_IO_Exception`, `Google_IO_Curl`, and `Google_IO_Stream` 2611. Removed methods `Google_Client::getIo` and `Google_Client::setIo` 2621. Refactored `Google_Http_Batch` and `Google_Http_MediaFileUpload` for Guzzle 2631. Added `Google_Client::getHttpClient` and `Google_Client::setHttpClient` for getting and 264setting the Guzzle `GuzzleHttp\ClientInterface` object. 265 266> NOTE: `PSR-7`-compatible libraries can now be used with this library. 267 268## Other Changes 269 270 - [`PSR 3`][PSR 3] `LoggerInterface` is now supported, and [Monolog][Monolog] is used for all 271 logging. As a result, all `Google_Logger`-related functionality has been removed: 272 1. Removed `Google_Logger_Abstract`, `Google_Logger_Exception`, `Google_Logger_File`, 273 `Google_Logger_Null`, and `Google_Logger_Psr` 274 1. `Google_Client::setLogger` now requires `Psr\Log\LoggerInterface` 275 - [`firebase/jwt`][Firebase JWT] is now used for all JWT signing and verifying. As a result, the 276 following classes have been changed or removed: 277 1. Removed `Google_Signer_P12` 278 1. Removed `Google_Verifier_Pem` 279 1. Removed `Google_Auth_LoginTicket` (see below) 280 - The following classes and methods have been removed in favor of [`google/auth`][Google Auth]: 281 1. Removed methods `Google_Client::getAuth` and `Google_Client::setAuth` 282 1. Removed `Google_Auth_Abstract` 283 - `Google_Auth_Abstract::sign` and `Google_Auth_Abstract::authenticatedRequest` have been 284 replaced by `Google_Client::authorize`. See the above examples for more details. 285 1. Removed `Google_Auth_AppIdentity`. This is now supported in [`google/auth`][Google Auth AppIdentity] 286 and is used automatically when `Google_Client::useApplicationDefaultCredentials` is called. 287 1. Removed `Google_Auth_AssertionCredentials`. Use `Google_Client::setAuthConfig` instead. 288 1. Removed `Google_Auth_ComputeEngine`. This is now supported in 289 [`google/auth`][Google Auth GCE], and is used automatically when 290 `Google_Client::useApplicationDefaultCredentials` is called. 291 1. Removed `Google_Auth_Exception` 292 1. Removed `Google_Auth_LoginTicket`. Calls to `Google_Client::verifyIdToken` now returns 293 the payload of the ID Token as an array if the verification is successful. 294 1. Removed `Google_Auth_OAuth2`. This functionality is now supported in [`google/auth`][Google Auth OAuth2] and wrapped in `Google_Client`. These changes will only affect applications calling `Google_Client::getAuth`, 295 as the methods on `Google_Client` have not changed. 296 1. Removed `Google_Auth_Simple`. This is now supported in [`google/auth`][Google Auth Simple] 297 and is used automatically when `Google_Client::setDeveloperKey` is called. 298 - `Google_Client::sign` has been replaced by `Google_Client::authorize`. This function 299 now takes a `GuzzleHttp\ClientInterface` object and uses the following decision tree for 300 authentication: 301 1. Uses Application Default Credentials when 302 `Google_Client::useApplicationDefaultCredentials` is called 303 - Looks for `GOOGLE_APPLICATION_CREDENTIALS` environment variable if set 304 - Looks in `~/.config/gcloud/application_default_credentials.json` 305 - Otherwise, uses `GCECredentials` 306 1. Uses API Key if set (see `Client::setDeveloperKey`) 307 1. Uses Access Token if set (call `Client::setAccessToken`) 308 1. Automatically refreshes access tokens if one is set and the access token is expired 309 - Removed `Google_Config` 310 - Removed `Google_Utils` 311 - [`Google\Auth\CacheInterface`][Google Auth CacheInterface] is used for all caching. As a result: 312 1. Removed `Google_Cache_Abstract` 313 1. Classes `Google_Cache_Apc`, `Google_Cache_File`, `Google_Cache_Memcache`, and 314 `Google_Cache_Null` now implement `Google\Auth\CacheInterface`. 315 - Removed `$boundary` constructor argument for `Google_Http_MediaFileUpload` 316 317[PSR 3]: https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-3-logger-interface.md 318[Guzzle 5]: https://github.com/guzzle/guzzle 319[Guzzle 6]: http://docs.guzzlephp.org/en/latest/psr7.html 320[Monolog]: https://github.com/Seldaek/monolog 321[Google Auth]: https://github.com/google/google-auth-library-php 322[Google Auth GCE]: https://github.com/google/google-auth-library-php/blob/master/src/GCECredentials.php 323[Google Auth OAuth2]: https://github.com/google/google-auth-library-php/blob/master/src/OAuth2.php 324[Google Auth Simple]: https://github.com/google/google-auth-library-php/blob/master/src/Simple.php 325[Google Auth AppIdentity]: https://github.com/google/google-auth-library-php/blob/master/src/AppIdentityCredentials.php 326[Google Auth CacheInterface]: https://github.com/google/google-auth-library-php/blob/master/src/CacheInterface.php 327[Firebase JWT]: https://github.com/firebase/php-jwt 328