adds UPGRADING.md

jordikroon · Oct 23, 2015 · a4cd92f · a4cd92f
1 parent ec32df1
commit a4cd92f
Showing 1 changed file with 299 additions and 0 deletions.
diff --git a/UPGRADING.md b/UPGRADING.md
@@ -0,0 +1,299 @@
+Google API Client Upgrade Guide
+===============================
+
+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:
+
+```php
+// 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](https://getcomposer.org) (We suggest installing
+composer [globally](http://symfony.com/doc/current/cookbook/composer.html)). 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:
+
+```php
+require_once 'vendor/autoload.php';
+```
+
+## Access Tokens are passed around as arrays instead of JSON strings
+
+**Before**
+
+```php
+$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**
+
+```php
+$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**
+
+```php
+$ticket = $client->verifyIdToken($idToken);
+$data = $ticket->getAttributes();
+$userId = $data['payload']['sub'];
+```
+
+**After**
+
+```php
+$userData = $client->verifyIdToken($idToken);
+$userId = $userData['sub'];
+```
+
+## `Google_Auth_AssertionCredentials` has been removed
+
+For service accounts, we now use `setAuthConfig` or `useApplicationDefaultCredentials`
+
+**Before**
+
+```php
+$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**
+
+```php
+$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**
+
+```php
+$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**
+
+```php
+$user_to_impersonate = '[email protected]';
+$client->setSubject($user_to_impersonate);
+```
+
+## `Google_Auth_AppIdentity` has been removed
+
+For App Engine authentication, we now use the underlying [`google/auth`][Google Auth] and
+call `useApplicationDefaultCredentials`:
+
+**Before**
+
+```php
+$client->setAuth(new Google_Auth_AppIdentity($client));
+$client->getAuth()
+    ->authenticateForScope('https://www.googleapis.com/auth/sqlservice.admin')
+```
+
+**After**
+
+```php
+$client->useDefaultApplicationCredentials();
+$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`][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**
+
+```php
+$request = new Google_Http_Request();
+$client->getAuth()->sign($request);
+```
+
+**After**
+
+```php
+$httpClient = new GuzzleHttp\Client();
+$client->authorize($httpClient);
+```
+
+**Before**
+
+```php
+$request = new Google_Http_Request();
+$response = $client->getAuth()->authenticatedRequest($request);
+```
+
+**After**
+
+```php
+$httpClient = new GuzzleHttp\Client();
+$client->authorize($httpClient);
+$request = $httpClient->createRequest('POST', $url);
+$response = $httpClient->send($request);
+```
+
+In addition, other methods that were callable on `Google_Auth_OAuth2` are now called
+on the `Google_Client` object:
+
+**Before**
+
+```php
+$client->getAuth()->refreshToken($token);
+$client->getAuth()->refreshTokenWithAssertion();
+$client->getAuth()->revokeToken($token);
+$client->getAuth()->isAccessTokenExpired();
+```
+
+**After**
+
+```php
+$client->refreshToken($token);
+$client->refreshTokenWithAssertion();
+$client->revokeToken($token);
+$client->isAccessTokenExpired();
+```
+
+## PHP 5.4 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](https://github.com/google/google-api-php-client/tree/v1-master) branch.
+
+## Guzzle 5 is used for HTTP Requests
+
+[`Guzzle 5`][Guzzle 5] is used for all HTTP Requests. As a result, all `Google_IO`-related
+functionality and `Google_Http`-related functionality has been changed or removed.
+
+1. Removed `Google_Http_Request`
+1. Removed `Google_IO_Abstract`, `Google_IO_Exception`, `Google_IO_Curl`, and `Google_IO_Stream`
+1. Removed methods `Google_Client::getIo` and `Google_Client::setIo`
+1. Refactored `Google_Http_Batch` and `Google_Http_MediaFileUpload` for Guzzle 5
+1. Added `Google_Http_Pool` for HTTP Pooling via Guzzle 5
+1. Added `Google_Client::getHttpClient` and `Google_Client::setHttpClient` for getting and
+setting the Guzzle 5 `GuzzleHttp\ClientInterface` object.
+
+## Other Changes
+
+ - [`PSR 3`][PSR 3] `LoggerInterface` is now supported, and [Monolog][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`
+    1. `Google_Client::setLogger` now requires `Psr\Log\LoggerInterface`
+ - [`firebase/jwt`][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`
+    1. Removed `Google_Verifier_Pem`
+    1. Removed `Google_Auth_LoginTicket` (see below)
+ - The following classes and methods have been removed in favor of [`google/auth`][Google Auth]:
+    1. Removed methods `Google_Client::getAuth` and `Google_Client::setAuth`
+    1. 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.
+    1. Removed `Google_Auth_AppIdentity`. This is now supported in [`google/auth`][Google Auth AppIdentity]
+    and is used automatically when `Google_Client::useApplicationDefaultCredentials` is called.
+    1. Removed `Google_Auth_AssertionCredentials`. Use `Google_Client::setAuthConfig` instead.
+    1. Removed `Google_Auth_ComputeEngine`. This is now supported in
+    [`google/auth`][Google Auth GCE], and is used automatically when
+    `Google_Client::useApplicationDefaultCredentials` is called.
+    1. Removed `Google_Auth_Exception`
+    1. 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.
+    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`,
+    as the methods on `Google_Client` have not changed.
+    1. Removed `Google_Auth_Simple`. This is now supported in [`google/auth`][Google Auth Simple]
+    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`)
+    1. Uses Access Token if set (call `Client::setAccessToken`)
+    1. Automatically refreshes access tokens if one is set and the access token is expired
+ - Removed `Google_Config`
+ - Removed `Google_Utils`
+ - [`Google\Auth\CacheInterface`][Google Auth CacheInterface] is used for all caching. As a result:
+    1. Removed `Google_Cache_Abstract`
+    1. Classes `Google_Cache_Apc`, `Google_Cache_File`, `Google_Cache_Memcache`, and
+    `Google_Cache_Null` now implement `Google\Auth\CacheInterface`.
+ - Removed `$boundary` constructor argument for `Google_Http_MediaFileUpload`
+
+[PSR 3]: https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-3-logger-interface.md
+[Guzzle 5]: https://github.com/guzzle/guzzle
+[Monolog]: https://github.com/Seldaek/monolog
+[Google Auth]: https://github.com/google/google-auth-library-php
+[Google Auth GCE]: https://github.com/google/google-auth-library-php/blob/master/src/GCECredentials.php
+[Google Auth OAuth2]: https://github.com/google/google-auth-library-php/blob/master/src/OAuth2.php
+[Google Auth Simple]: https://github.com/google/google-auth-library-php/blob/master/src/Simple.php
+[Google Auth AppIdentity]: https://github.com/google/google-auth-library-php/blob/master/src/AppIdentityCredentials.php
+[Google Auth CacheInterface]: https://github.com/google/google-auth-library-php/blob/master/src/CacheInterface.php
+[Firebase JWT]: https://github.com/firebase/php-jwt