Google Contacts PHP library

We’re happy to announce that we have recently open sourced a Google Contacts API PHP client library. This library is MIT licensed (so anyone can use it) and available on our GitHub account. For more information about Rapid Web Services Services open source efforts, please visit our Rapid Web Services open source mini-site.

About

This Google Contacts API library is designed for use in PHP frameworks and general PHP web applications. It uses version 3 of the Google Contacts API, and supports association with a Google account via OAUTH. After a Google account is associated, it is possible to retrieve existing contacts from the account, create new contacts and update any existing contacts.

Retrieved Google contacts are represented by a Contact object. Contacts are retrieved via a ContactFactory. The library has appropriate namespaces and supports a sensible and easy to understand syntax.

This was created due to the lack of any pre-existing, accessible PHP libraries for the latest version of the Google Contacts API (v3). It has been open sourced with the MIT license to aid other developers who may need to integrate Google Contacts into their PHP websites or applications.

Installation

To install the Rapid Web Services PHP Google Contacts (v3) API and its dependencies, you should make use of the Composer dependency manager. Simply add the following to your composer.json file then run composer update.

{
  "require": {
       "rapidwebltd/php-google-contacts-v3-api": "dev-master"
   }
}

Setup and account association

The first step after installation is to connect (or associate) the Google account whose contacts you wish to manage. This involves retrieving relevant Google Contacts API credentials and then modifying the library’s configuration appropriately. After configuration changes are made, you must run through the OAUTH process to acquire a refresh token, which is used to permit continual access to the contacts within the associated Google account.

The following step-by-step instructions should guide you through this process:

If you have not done so already, install the library and its required dependencies using composer.
Copy or rename .config_blank.json to .config.json. Note the dot (.) at the beginning of the file name.
Fill in the clientID, clientSecret and redirectUri in .config.json.
- Note that redirectUri should be configured to point towards the redirect-handler.php file.
- The clientID and clientSecret can be found in the Google Developers console at https://console.developers.google.com/ under ‘APIs & auth’ -> ‘Credentials’.
Go to authorise-application.php in a web browser. This should give you a URL to authorise your application for Google Contacts.
Go to the authorisation URL provided by the previous step.
Accept the permissions requested on the page displayed. You should then be redirected back to the redirect-handler.php file.
The page generated by the redirect-handler.php file should then present you with a refresh token. Copy this into your .config.json.
Setup is done!

Usage

After the library has been installed and the setup and account association steps have been completed, you can make use of the library.

Remember to include the following require code on any pages you wish to make use of this library.

require_once '../../../vendor/autoload.php';

Retrieving Google Contacts

The following code will retrieve all contacts from the associated Google account.

$contacts = rapidweb\googlecontacts\factories\ContactFactory::getAll();

var_dump($contacts);

The ContactFactory::getAll() method will return an array of Contact objects. The contact’s details will be available as public member variables of these objects.

The selfURL contained within each Contact object is the unique reference to this particular contact. If you need to retrieve a specific contact in the future, you will need to store this selfURL.

To retrieve a specific contact (by its selfURL), use the following code.

$selfURL = "...";

$contact = rapidweb\googlecontacts\factories\ContactFactory::getBySelfURL($selfURL);

var_dump($contact);

This ContactFactory::getBySelfURL method will return a single Contact object.

Google Contact properties are accessed as follows.

$selfURL = "...";

$contact = rapidweb\googlecontacts\factories\ContactFactory::getBySelfURL($selfURL);

echo $contact->name;
echo $contact->phoneNumber;
echo $contact->email;

Updating existing Google Contacts

The updating of Google Contacts using this library is done in a very object orientated manner.

You must first retrieve a Contact object using one of the methods mentioned previously. You can then modify the contact object’s public member variables. To save these changes back to the Google Contacts service, you then pass the modified object to the ContactFactory::submitUpdates($contact) method.

The following code demonstrates in full retrieving a contact, modifying it and submitting the updates.

$selfURL = "...";

$contact = rapidweb\googlecontacts\factories\ContactFactory::getBySelfURL($selfURL);

var_dump($contact);

$contact->name = 'Test';
$contact->phoneNumber = '07812363789';
$contact->email = 'test@example.com';

$contactAfterUpdate = rapidweb\googlecontacts\factories\ContactFactory::submitUpdates($contact);

var_dump($contactAfterUpdate);

Creating new Google Contacts

Creating a new Google Contact is very easy. Simply call the ContactFactory::create($name, $phoneNumber, $emailAddress) method, passing through appropriate parameters. This method will return the created contact as a Contact object including its newly assigned selfURL.

$name = "Frodo Baggins";
$phoneNumber = "06439111222";
$emailAddress = "frodo@example.com";

$newContact = rapidweb\googlecontacts\factories\ContactFactory::create($name, $phoneNumber, $emailAddress);

Issues & Contributions

If you find any bugs or problems with this library (or wish to suggest a new feature), please create a new GitHub issue. We will try to address all new issues appropriately.

We’re also open to code contributions, so please feel free to submit a pull request to the PHP Google Contacts API GitHub repository.

PHP library for the Google Contacts API (v3)