yidas/google-apiclient-helper

Google APIs Client Helper - Easy way to accessing Google APIs with PHP

1.1.0 2018-09-15 07:29 UTC

Requires

• php: >=5.4
• google/apiclient: ^2.0

MIT

• helper
• php sdk
• google api
• google api client

README

Google API Client Helper

Google APIs Client Helper - Easy way to accessing Google APIs with PHP

FEATURES

• Easy way to develop and manage Google API application

• Documentation supported for Service SDK

• Simple usage for each Service

This Helper is based on google-api-php-client and google-api-php-client-services.

OUTLINE

• Demonstration
• Requirements
• Installation
• Google Client
  • Configuration
    • Config Array Method
    • Config Chain Method
    • Encapsulating Method
  • AccessToken Usage
    • refreshAccessToken()
    • verifyAccessToken()
    • verifyScopes()
  • Implementation
• Google Services
  • People
    • Attributes
    • getSimpleContacts()
    • createContact()
    • updateContact()
    • deleteContact()
• Exceptions
• Reference

DEMONSTRATION

$client = \yidas\google\apiHelper\Client::setClient()
    ->setApplicationName('Google API')
    ->setAuthConfig('/path/google_api_secret.json')
    ->setRedirectUri("http://{$_SERVER['HTTP_HOST']}" . dirname($_SERVER['PHP_SELF'])
    ->setAccessToken($accessToken)
    ->getClient();

if ($accessToken = ClientHelper::refreshAccessToken()) {
    // saveAccessToken($accessToken)
}

// People Service uses Google_Client from Client helper above
$contacts = \yidas\google\apiHelper\services\People::getSimpleContacts();

REQUIREMENTS

This library requires the following:

• PHP 5.4.0+
• google/apiclient 2.0+

INSTALLATION

Run Composer in your project:

composer require yidas/google-apiclient-helper

Then you could call it after Composer is loaded depended on your PHP framework:

require __DIR__ . '/vendor/autoload.php';

use yidas\google\apiHelper\Client;

GOOGLE CLIENT

Configuration

There are many way to set Google_Client by Helper:

Config Array Method

The config keys refer to the methods of Google_Client. For exmaple, authConfig refers to Google_Client->setAuthConfig().

$client = \yidas\google\apiHelper\Client::setClient([
        'applicationName' => 'Google API',
        'authConfig' => '/path/google_api_secret.json',
        'redirectUri' => "http://{$_SERVER['HTTP_HOST']}" . dirname($_SERVER['PHP_SELF'],
        ])
    ->getClient();

Config Chain Method

The methods refer to the same method names of Google_Client. For exmaple, setAuthConfig() refers to Google_Client->setAuthConfig().

$client = \yidas\google\apiHelper\Client::setClient()
    ->setApplicationName('Google API')
    ->setAuthConfig('/path/google_api_secret.json')
    ->setRedirectUri("http://{$_SERVER['HTTP_HOST']}" . dirname($_SERVER['PHP_SELF'])
    ->getClient();

Encapsulating Method

$client = new Google_Client();
$client->setAuthConfig('/path/google_api_secret.json');
\yidas\google\apiHelper\Client::setClient($client);

After encapsulating Google_Client into Helper, the Helper would share with the same Google_Client object.

AccessToken Usage

refreshAccessToken()

Simple way to get refreshed access token or false expired to skip

public static array|false refreshAccessToken()

Example:

$client = \yidas\google\apiHelper\Client::setClient()
    ->setApplicationName('Google API')
    ->setAuthConfig('/path/google_api_secret.json')
    ->setRedirectUri("http://{$_SERVER['HTTP_HOST']}" . dirname($_SERVER['PHP_SELF'])
    ->setAccessToken($accessToken)
    ->getClient();

// Simple way to get refreshed access token or false expired to skip
if ($accessToken = ClientHelper::refreshAccessToken()) {
    // saveAccessToken($accessToken)
}

Helper handles the setting setAccessType('offline') & setApprovalPrompt('force') for refresh token.

verifyAccessToken()

Verify an access_token. This method will verify the current access_token by Google API, if one isn't provided.

public static array|false verifyAccessToken(string $accessToken=null)

verifyScopes()

Verify scopes of tokenInfo by access_token. This method will verify the current access_token by Google API, if one isn't provided.

public static array|false verifyScopes(array $scopes, string $accessToken=null)

Example:

$result = \yidas\google\apiHelper\Client::verifyScopes([
    'https://www.googleapis.com/auth/userinfo.profile',
]);

Implementation

There are more implementations such as addScope() or createAuthUrl() for OAuth register, you cloud refer following sample code:

yidas/php-google-api-sample

GOOGLE SERVICES

You could directly use any Service Helpers which uses Google_Client from yidas\google\apiHelper\Client:

use \yidas\google\apiHelper\services\People as PeopleHelper;
\yidas\google\apiHelper\Client::setClient([...])

$contacts = PeopleHelper::getSimpleContacts();

Or you could reset a Google_Client for each Service Helper:

use \yidas\google\apiHelper\services\People as PeopleHelper;

PeopleHelper::setClient($googleClient);
// PeopleHelper::method()...

Use getService() to get back current Google Service object for advanced usage:

$service = \yidas\google\apiHelper\services\People::getService();
// $service->people_connections->...

People

API Document: https://developers.google.com/people/api/rest/

People helper has smart call refered to Google_Service_PeopleService_Person methods, which provides easy interface to setValue() for a person.

// Simple setValue() example
\yidas\google\apiHelper\services\People::newPerson
    ->setEmailAddresses('[e-mail]')
    ->setPhoneNumbers('+886')
    ->setBiographies("I'm a note");

Attributes

It's easy to set attributes for a person by Helper, which provides three types for input data:

1. Origin Object

Input by original Google Attribute Classes that are not so convenience.

$gPhoneNumber = new Google_Service_PeopleService_PhoneNumber;
$gPhoneNumber->setValue('+886');
\yidas\google\apiHelper\services\People::setPhoneNumbers($gPhoneNumber);

2. Array

Input by array type would map to the API key-value setting.

\yidas\google\apiHelper\services\People::setPhoneNumbers(['value' => '+886']);

3. String

Input by string type would enable Helper attribute handler which automatically settles value for all attributes.

\yidas\google\apiHelper\services\People::setPhoneNumbers('+886');

getSimpleContacts()

Get simple contact data with parser

public static array getContacts()

Example:

// Get formated list by Helper
$contacts = \yidas\google\apiHelper\services\People::getSimpleContacts();

Result:

Array
(
    [0] => Array
        (
            [id] => people/c26081557840316580
            [name] => Mr.Nick
            [email] => 
            [phone] => 0912 345 678
        )
    ...

This is simple fields parser, you could use listPeopleConnections() if you need all fields.

createContact()

Create a People Contact

public static Google_Service_PeopleService_Person createContact()

Example:

$person = \yidas\google\apiHelper\services\People::newPerson()
    ->setNames('Nick')
    ->setEmailAddresses('[e-mail]')
    ->setPhoneNumbers('+886')
    ->createContact();

Resource Name: $person->resourceName or $person['resourceName'].

updateContact()

Update a People Contact

public static Google_Service_PeopleService_PeopleEmpty updateContact(array $optParams=null)

Example:

$person = \yidas\google\apiHelper\services\People::findByResource($resourceName)
    ->setNames('Nick')
    ->setEmailAddresses('[e-mail]')
    ->setPhoneNumbers('+886')
    ->updateContact();

deleteContact

Delete a People Contact

public static Google_Service_PeopleService_PeopleEmpty deleteContact(string $resourceName=null, array $optParams=[])

Example:

$person = \yidas\google\apiHelper\services\People::deleteContact($resourceName);

You could also use find pattern:

$person = \yidas\google\apiHelper\services\People::findByResource($resourceName)
    ->deleteContact();

EXCEPTIONS

For all Google Exception including Client and Services:

try {} catch (\Google_Exception $e) {}

Otherwise, for Google Services only:

try {} catch (\Google_Service_Exception $e) {}

REFERENCE

• Google API PHP Client SDK

• Google API PHP Client Serivces SDK

• Google Identity Platform

• Google People API