Google Provisioning API Developer's Guide: PHP

Using the PHP Client Library

The following subsections explain how to use the Zend Google Data Client Library to access Provisioning API functionality. Each subsection explains the PHP client library methods for specific API functionality.

Authenticating to your Domain Methods for User Accounts Creating a User Account Retrieving a User Account Retrieving all Users in a Domain Retrieving List of 100 Users Updating a User Account Suspending a User Account Restoring a User Account Deleting a User Account Methods for Nicknames Creating a Nickname Retrieving a Nickname Retrieving all Nicknames for a User Retrieving all Nicknames in a Domain Retrieving List of 100 Nicknames Deleting a Nickname

Methods for Email Lists Creating an Email List Retrieving an Email List Retrieving all Email List Subscriptions for a User Retrieving all Email Lists in a Domain Retrieving List of 100 Email Lists Deleting an Email List Methods for Email List Recipients Adding an Address to an Email List Retrieving All Subscribers to an Email List Retrieving List of 100 Email List Subscribers Deleting an Address from an Email List Methods for Handling Errors Identifying Errors in API Responses

Authenticating to your Domain

Before making API calls with the PHP client library, you must construct a new Zend_Gdata_Gapps object. In the constructor, set your authentication information as follows:

$client = Zend_Gdata_ClientLogin::getHttpClient($email, $password, Zend_Gdata_Gapps::AUTH_SERVICE_NAME);
$service = new Zend_Gdata_Gapps($client, $domain)

Here, replace $domain with the domain to which you are authenticating, $email with your domain administrator email address, and $password with your domain administrator password.

Methods for User Accounts

Creating a User Account

To create a user account using the PHP client library, call one of the following methods. These methods all return a UserEntry XML response, which the PHP client library converts to a UserEntry object.

$service->createUser($username, $familyName, $givenName, $password, $passwordHashFunction=null, $quota=null)

Note: Not all partners have the ability to adjust the disk space quota allocated to users. This method takes the following arguments:

• The username argument contains the unique name that identifies the account owner.
• The familyName argument contains the user's last name.
• The givenName argument contains the user's first name.
• The password argument contains the password for the user account.
• The passwordHashFunction argument specifies the hash format of the password parameter.
• The quota argument identifies the amount of disk space in MB that will be allocated to the user account.

Retrieving a User Account

To retrieve information about a user account using the PHP client library, call the following method. This method returns a UserEntry XML response, which the PHP client library converts to a UserEntry object.

$service->retrieveUser($username)

The only argument that you need to pass to the method is the username associated with the account that you wish to retrieve.

Retrieving all Users in a Domain

To retrieve all of the users in a domain, you can call the following method in the PHP client library. This method returns a UserFeed XML response, which the PHP client library converts to a UserFeed object.

$service->retrieveAllUsers()

Retrieving List of 100 Users

This method allows you to control the size of your result set when you request all of the users in your domain. As discussed in the Results Pagination section, the PHP client library offers methods that allow you to request all results or to request 100 results at a time. If you use the latter method, you will need to ensure that your code requests additional pages of results as necessary.

To retrieve a list of 100 users in your domain, you can call the following method in the PHP client library. This method returns a UserFeed XML response, which the PHP client library converts to a UserFeed object.

$service->retrievePageOfUsers($startUsername=null)

The only argument that you need to pass to the method is the first username that should appear in your result set. Usernames are ordered case-insensitively by ASCII value.

Updating a User Account

To update a user account using the PHP client library, first retrieve a UserEntry as described above in Retrieving a User Account, make any desired changes to the entry, and then call:

$userEntry->save()

This method returns an updated UserEntry XML response for the user, which the PHP client library converts to a UserEntry object.

Suspending a User Account

To suspend a user account using the PHP client library, call the following method. This method returns a UserEntry XML response, which the PHP client library converts to a UserEntry object.

$service->suspendUser($username)

The only argument that you need to pass to the method is the name of the user whose account you wish to suspend.

Restoring a User Account

To restore a user account using the PHP client library, call the following method. This method returns a UserEntry XML response, which the PHP client library converts to a UserEntry object.

$service->restoreUser($username)

The only argument that you need to pass to the method is the name of the user whose account you wish to restore.

Deleting a User Account

To delete a user account using the PHP client library, call the following method:

$service->deleteUser($username)

The only argument that you need to pass to the method is the name of the user whose account you wish to delete.

Methods for Nicknames

Creating a Nickname

To create a nickname using the PHP client library, call the following method. This method returns a NicknameEntry XML response, which the PHP client library converts to a NicknameEntry object.

$service->createNickname($username, $nickname)

This method takes two arguments:

• The username argument identifies the user account for which you are creating a nickname.
• The nickname argument identifies the nickname for the user account.

Retrieving a Nickname

To retrieve information about a nickname using the PHP client library, call the following method. This method returns a NicknameEntry XML response, which the PHP client library converts to a NicknameEntry object.

$service->retrieveNickname($nickname)
The only argument that you need to pass to the method is the nickname you wish to retrieve. 




Retrieving all Nicknames for a User Account


To retrieve all of the nicknames created for a user account, you can call the following method in the PHP client library. This method returns a NicknameFeed XML response, which the PHP client library converts to a NicknameFeed object.
$service->retrieveNicknames($username)

The only argument that you need to pass to the method is the username for which you wish to retrieve nicknames. 




Retrieving all Nicknames in a Domain


To retrieve all of the nicknames in a domain, you can call the following method in the PHP client library. This method returns a NicknameFeed XML response, which the PHP client library converts to a NicknameFeed object.
service.retrieveAllNicknames()





Retrieving List of 100 Nicknames


This method allows you to control the size of your result set when you request all of the nicknames in your domain. As discussed in the Results Pagination section, the PHP client library offers methods that allow you to request all results or to request 100 results at a time. If you use the latter method, you will need to ensure that your code requests additional pages of results as necessary.

To retrieve a list of 100 nicknames in your domain, you can call the following method in the PHP client library. This method returns a NicknameFeed XML response, which the PHP client library converts to a NicknameFeed object.
$service->retrievePageOfNicknames($startNickname=null)

The only argument that you need to pass to the method is the first nickname that should appear in your result set. Nicknames are ordered case-insensitively by ASCII value.




Deleting a Nickname


To delete a nickname using the PHP client library, call the following method:
$service->deleteNickname($nickname)

The only argument that you need to pass to the method is the name of the nickname that you wish to delete.

Methods for Email Lists


Creating an Email List


To create an email list using the PHP client library, call the following method. This method returns an EmailListEntry XML response, which the PHP client library converts to an EmailListEntry object.
$service->createEmailList($listName)

The only argument that you need to pass to the method is the name of the email list that you wish to create.

Note: A newly created email list does not have any subscribers. You must call the AddRecipientToEmailList method to add subscribers to an email list.

Retrieving an Email List


To retrieve information about an email list using the PHP client library, call the following method. This method returns a EmailListEntry XML response, which the PHP client library converts to a EmailListEntry object.
$service->retrieveEmailList($listName)

The only argument that you need to pass to the method is the name of the email list that you wish to retrieve. 




Retrieving all Email Lists for a User Account


To retrieve all of the email lists that a user is a recipient of, you can call the following method in the PHP client library. This method returns a EmailListFeed XML response, which the PHP client library converts to a EmailListFeed object.
$service->retrieveEmailLists($recipient)

The only argument that you need to pass to the method is the username or email address of a hosted user for which you wish to retrieve email list subscriptions. 




Retrieving all Email Lists in a Domain


To retrieve all of the email lists in a domain, you can call the following method in the PHP client library. This method returns a EmailListFeed XML response, which the PHP client library converts to a EmailListFeed object.
$service->retrieveAllEmailLists()





Retrieving List of 100 Email Lists


This method allows you to control the size of your result set when you request all of the email lists in your domain. As discussed in the Results Pagination section, the PHP client library offers methods that allow you to request all results or to request 100 results at a time. If you use the latter method, you will need to ensure that your code requests additional pages of results as necessary.

To retrieve a list of 100 email lists in your domain, you can call the following method in the PHP client library. This method returns a EmailListFeed XML response, which the PHP client library converts to a EmailListFeed object.
$service->retrievePageOfEmailLists($startEmailListName=null)

The only argument that you need to pass to the method is the first email list that should appear in your result set. Email list names are ordered case-insensitively by ASCII value.




Deleting an Email List



To delete an email list using the PHP client library, call the following method:
$service->deleteEmailList($listName)

The only argument that you need to pass to the method is the name of the email list that you wish to delete.
Note: When you delete an email list, the Provisioning API will automatically delete all recipients from the email list as well.

Methods for Email List Recipients


Adding an Address to an Email List


To add an email address to an email list using the PHP client library, call the following method. This method returns an EmailListRecipientEntry XML response, which the PHP client library converts to a EmailListRecipientEntry object.
$service->addRecipientToEmailList($recipient, $listName)

This method takes two arguments:

The recipient argument identifies the email address that is being added to an email list.
The listName argument identifies the email list to which the address is being added.


Retrieving all Subscribers to an Email List


To retrieve a list of all of the subscribers to an email list, you can call the following method in the PHP client library. This method returns a EmailListRecipientFeed XML response, which the PHP client library converts to a EmailListRecipientFeed object.
$service->retrieveAllRecipients($listName)

The only argument that you need to pass to the method is the name of the email list for which you wish to retrieve a subscriber list.




Retrieving List of 100 Email List Subscribers


This method allows you to control the size of your result set when you request all of the recipients of an email list. As discussed in the Results Pagination section, the PHP client library offers methods that allow you to request all results or to request 100 results at a time. If you use the latter method, you will need to ensure that your code requests additional pages of results as necessary.

To retrieve a list of 100 email list recipients, you can call the following method in the PHP client library. This method returns a EmailListRecipientFeed XML response, which the PHP client library converts to a EmailListRecipientFeed object.
$service->retrievePageOfRecipients($listName, $startRecipient=null)

This method takes two arguments. The first argument is the name of the email list for which you are retrieving recipients, and the second argument is the first email address that should appear in your result set. Email addresses are ordered case-insensitively by ASCII value.




Deleting an Address from an Email List


To delete an email address from an email list using the PHP client library, call the following method:
$service->removeRecipientFromEmailList($recipient, $listName)

This method takes two arguments:

The recipient argument identifies the email address that is being removed from an email list.
The listName argument identifies the email address to which the address is being removed.


Methods for Handling Errors


Identifying Errors in API Responses


The PHP client library will throw a ServiceException when it receives an error response from the Provisioning API. Other types of exceptions may also be thrown for other types of errors. To process or log a ServiceException, retrieve the error array by calling the $e->getErrors() method, then calling $e->getErrorCode() or $e->getReason() on each element of that array to determine the type of errors that the Provisioning API returned. The presence of individual error codes can also quickly be determined by calling $e->hasError($errorCode).

The sample code below demonstrates how you would catch a ServiceException in the Provisioning API:

  try{
    // Some API actions
  } catch (Zend_Gdata_Gapps_ServiceException $e) {
    if ($e->hasError(Zend_Gdata_Gapps_Error::ENTITY_DOES_NOT_EXIST) {
      // If this is an ENTITY_DOES_NOT_EXIST error, return null        
      return null;
    }
    else {
      // Outherwise, just print the errors that occured and exit
      foreach ($e->getErrors() as $error) {
        echo "Error encountered: {$e->getReason()} ({$e->getErrorCode()})\n"
      }
      exit();
    }
  }


A complete list of error codes is provided in Appendix D - GData Error Codes.