Linux ip-172-26-7-228 5.4.0-1103-aws #111~18.04.1-Ubuntu SMP Tue May 23 20:04:10 UTC 2023 x86_64
Your IP : 18.216.253.84
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 = '1234567890-a1b2c3d4e5f6g7h8i@developer.gserviceaccount.com';
$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 = 'user@example.org';
$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 = 'user@example.org';
$client->setSubject($user_to_impersonate);
```
Additionally, `Google_Client::loadServiceAccountJson` has been removed in favor
of `Google_Client::setAuthConfig`:
**Before**
```php
$scopes = [ Google_Service_Books::BOOKS ];
$client->loadServiceAccountJson('/path/to/service-account.json', $scopes);
```
**After**
```php
$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`][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->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`][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
// create an authorized HTTP client
$httpClient = $client->authorize();
// OR add authorization to an existing client
$httpClient = new GuzzleHttp\Client();
$httpClient = $client->authorize($httpClient);
```
**Before**
```php
$request = new Google_Http_Request();
$response = $client->getAuth()->authenticatedRequest($request);
```
**After**
```php
$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**
```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 and PSR-7 are used for HTTP Requests
The HTTP library Guzzle is used for all HTTP Requests. By default, [`Guzzle 6`][Guzzle 6]
is used, but this library is also compatible with [`Guzzle 5`][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`
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
1. 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`][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`
- [`PSR-6`][PSR 6] cache 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`.
1. Google Auth provides simple [caching utilities][Google Auth Cache] which
are used by default unless you provide alternatives.
- Removed `$boundary` constructor argument for `Google_Http_MediaFileUpload`
[PSR 3]: https://www.php-fig.org/psr/psr-3/
[PSR 6]: https://www.php-fig.org/psr/psr-6/
[Guzzle 5]: https://github.com/guzzle/guzzle
[Guzzle 6]: http://docs.guzzlephp.org/en/latest/psr7.html
[Monolog]: https://github.com/Seldaek/monolog
[Google Auth]: https://github.com/google/google-auth-library-php
[Google Auth Cache]: https://github.com/googleapis/google-auth-library-php/tree/master/src/Cache
[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
[Firebase JWT]: https://github.com/firebase/php-jwt
|