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