第 18 章 Zend_Gdata

Zend_Gata is composed of several types of classes:

Google data services are based upon the Atom Publishing Protocol (APP) and the Atom syndication format. To interact with APP or Google services using the Zend_Gdata component, you need to use the service classes such as Zend_Gdata_App, Zend_Gdata, Zend_Gdata_Spreadsheets, etc. These service classes provide methods to retrieve data from services as feeds, insert new entries into feeds, update entries, and delete entries.

Note: A full example of working with Zend_Gdata is available in the demos/Zend/Gdata directory. This example is runnable from the command-line, but the methods contained within are easily portable to a web application.

The Zend Framework naming standards require that all classes be named based upon the directory structure in which they are located. For instance, extensions related to Spreadsheets are stored in: Zend/Gdata/Spreadsheets/Extension/... and, as a result of this, are named Zend_Gdata_Spreadsheets_Extension_.... This causes a lot of typing if you're trying to construct a new instance of a spreadsheet cell element!

We've implemented a magic factory method in all service classes (such as Zend_Gdata_App, Zend_Gdata, Zend_Gdata_Spreadsheets) that should make constructing new instances of data model, query and other classes much easier. This magic factory is implemented by using the magic __call method to intercept all attempts to call $service->newXXX(arg1, arg2, ...). Based off the value of XXX, a search is performed in all registered 'packages' for the desired class. Here's some examples:

$ss = new Zend_Gdata_Spreadsheets();

// creates a Zend_Gdata_App_Spreadsheets_CellEntry
$entry = $ss->newCellEntry();

// creates a Zend_Gdata_App_Spreadsheets_Extension_Cell
$cell = $ss->newCell();
$cell->setText('My cell value');
$cell->setRow('1');
$cell->setColumn('3');
$entry->cell = $cell;

// ... $entry can then be used to send an update to a Google Spreadsheet

        

Each service class in the inheritance tree is responsible for registering the appropriate 'packages' (directories) which are to be searched when calling the magic factory method.

Most Google Data services require client applications to authenticate against the Google server before accessing private data, or saving or deleting data. There are two implementations of authentication for Google Data: AuthSub and ClientLogin. Zend_Gdata offers class interfaces for both of these methods.

Most other types of queries against Google Data services do not require authentication.

Zend_Gdata makes use of Zend_Http_Client to send requests to google.com and fetch results. The response to most Google Data requests is returned as a subclass of the Zend_Gdata_App_Feed or Zend_Gdata_App_Entry classes.

Zend_Gdata assumes your PHP application is running on a host that has a direct connection to the Internet. The Zend_Gdata client operates by contacting Google Data servers.

Create a new object of class Zend_Gdata_App, Zend_Gdata, or one of the subclasses available that offer helper methods for service-specific behavior.

The single optional parameter to the Zend_Gdata_App constructor is an instance of Zend_Http_Client. If you don't pass this parameter, Zend_Gdata creates a default Zend_Http_Client object, which will not have associated credentials to access private feeds. Specifying the Zend_Http_Client object also allows you to pass configuration options to that client object.

$client = new Zend_Http_Client();
$client->setConfig( ...options... );

$gdata = new Zend_Gdata($client);

        

Also see the sections on authentication for methods to create an authenticated Zend_Http_Client object.

You can specify parameters to customize queries with Zend_Gdata. Query parameters are specified using subclasses of Zend_Gdata_Query. The Zend_Gdata_Query class includes methods to set all query parameters used throughout GData services. Individual services, such as Spreadsheets, also provide query classes to defined parameters which are custom to the particular service and feeds. Spreadsheets includes a CellQuery class to query the Cell Feed and a ListQuery class to query the List Feed, as different query parameters are applicable to each of those feed types. The GData-wide parameters are described below.

There is a get function for each set function.

$query = new Zend_Gdata_Query();
$query->setMaxResults(10);
echo $query->getMaxResults();   // returns 10

        

The Zend_Gdata class also implements "magic" getter and setter methods, so you can use the name of the parameter as a virtual member of the class.

$query = new Zend_Gdata_Query();
$query->maxResults = 10;
echo $query->maxResults;        // returns 10

        

You can clear all parameters with the resetParameters() function. This is useful to do if you reuse a Zend_Gdata object for multiple queries.

$query = new Zend_Gdata_Query();
$query->maxResults = 10;
// ...get feed...

$query->resetParameters();      // clears all parameters
// ...get a different feed...

        

Use the getFeed() function to retrieve a feed from a specified URI. This function returns an instance of class specified as the second argument to getFeed, which defaults to Zend_Gdata_Feed.

$gdata = new Zend_Gdata();
$query = new Zend_Gdata_Query(
        'http://www.blogger.com/feeds/blogID/posts/default');
$query->setMaxResults(10);
$feed = $gdata->getFeed($query);

        

See later sections for special functions in each helper class for Google Data services. These functions help you to get feeds from the URI that is appropriate for the respective service.

When retrieving a feed that contains a large number of entries, the feed may be broken up into many smaller "pages" of feeds. When this occurs, each page will contain a link to the next page in the series. This link can be accessed by calling getLink('next'). The following example shows how to retrieve the next page of a feed:

function getNextPage($feed) {
    $nextURL = $feed->getLink('next');
    if ($nextURL !== null) {
        return $gdata->getFeed($nextURL);
    } else {
        return null;
    }
}

        

If you would prefer not to work with pages in your application, pass the first page of the feed into Zend_Gdata_App::retrieveAllEntriesForFeed(), which will consolidate all entries from each page into a single feed. This example shows how to use this function:

$gdata = new Zend_Gdata();
$query = new Zend_Gdata_Query(
        'http://www.blogger.com/feeds/blogID/posts/default');
$feed = $gdata->retrieveAllEntriesForFeed($gdata->getFeed($query));

        

Keep in mind when calling this function that it may take a long time to complete on large feeds. You may need to increase PHP's execution time limit by calling set_time_limit().

After retrieving a feed, you can read the data from the feed or the entries contained in the feed using either the accessors defined in each of the data model classes or the magic accessors. Here's an example:

$client = Zend_Gdata_ClientLogin::getHttpClient($user, $pass, $service);
$gdata = new Zend_Gdata($client);
$query = new Zend_Gdata_Query(
        'http://www.blogger.com/feeds/blogID/posts/default');
$query->setMaxResults(10);
$feed = $gdata->getFeed($query);
foreach ($feed as $entry) {
    // using the magic accessor
    echo 'Title: ' . $entry->title->text;
    // using the defined accessors
    echo 'Content: ' . $entry->getContent()->getText();
}

        

After retrieving an entry, you can update that entry and save changes back to the server. Here's an example:

$client = Zend_Gdata_ClientLogin::getHttpClient($user, $pass, $service);
$gdata = new Zend_Gdata($client);
$query = new Zend_Gdata_Query(
        'http://www.blogger.com/feeds/blogID/posts/default');
$query->setMaxResults(10);
$feed = $gdata->getFeed($query);
foreach ($feed as $entry) {
    // update the title to append 'NEW'
    echo 'Old Title: ' . $entry->title->text;
    $entry->title->text = $entry->title->text . ' NEW';

    // update the entry on the server
    $newEntry = $entry->save();
    echo 'New Title: ' . $newEntry->title->text;
}

        

The Zend_Gdata object has a function post() with which you can upload data to save new entries to Google Data services.

You can use the data model classes for each service to construct the appropriate entry to post to Google's services. The post() function will accept a child of Zend_Gdata_App_Entry as data to post to the service. The method returns a child of Zend_Gdata_App_Entry which represents the state of the entry as it was returned from the server.

Alternatively, you could construct the XML structure for an entry as a string and pass the string to the post() function.

$gdata = new Zend_Gdata($authenticatedHttpClient);

$entry = $gdata->newEntry();
$entry->title = $gdata->newTitle('Playing football at the park');
$content = 
    $gdata->newContent('We will visit the park and play football');
$content->setType('text');
$entry->content = $content;

$entryResult = $gdata->insertEntry($entry,
        'http://www.blogger.com/feeds/blogID/posts/default');

echo 'The <id> of the resulting entry is: ' . $entryResult->id->text;

        

To post entries, you must be using an authenticated Zend_Http_Client that you created using the Zend_Gdata_AuthSub or Zend_Gdata_ClientLogin classes.

Option 1: The Zend_Gdata object has a function delete() with which you can delete entries from Google Data services. Pass the edit URL value from a feed entry to the delete() method.

Option 2: Alternatively, you can call $entry->delete() on an entry retrieved from a Google service.

$gdata = new Zend_Gdata($authenticatedHttpClient);
// a Google Data feed
$feedUri = ...;
$feed = $gdata->getFeed($feedUri);
foreach ($feed as $feedEntry) {
    // Option 1 - delete the entry directly
    $feedEntry->delete();
    // Option 2 - delete the entry by passing the edit URL to
    // $gdata->delete()
    // $gdata->delete($feedEntry->getEditLink()->href);
}

        

To delete entries, you must be using an authenticated Zend_Http_Client that you created using the Zend_Gdata_AuthSub or Zend_Gdata_ClientLogin classes.