repo_zf1/documentation/manual/en/module_specs/Zend_Gdata-Introduction.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect1 id="zend.gdata.introduction">
    <title>Introduction</title>

    <para>
        Google Data <acronym>API</acronym>s provide programmatic interface to some of Google's
        online services. The Google data Protocol is based upon the <ulink
            url="http://ietfreport.isoc.org/idref/draft-ietf-atompub-protocol/">Atom Publishing
            Protocol</ulink> and allows client applications to retrieve data matching queries,
        post data, update data and delete data using standard <acronym>HTTP</acronym> and the
        Atom syndication formation. The <classname>Zend_Gdata</classname> component is a
        <acronym>PHP</acronym> 5 interface for accessing Google Data from <acronym>PHP</acronym>.
        The <classname>Zend_Gdata</classname> component also supports accessing other services
        implementing the Atom Publishing Protocol.
    </para>

    <para>
        See
        <ulink url="http://code.google.com/apis/gdata/">http://code.google.com/apis/gdata/</ulink>
        for more information about Google Data <acronym>API</acronym>.
    </para>

    <para>
        The services that are accessible by <classname>Zend_Gdata</classname> include the
        following:

        <itemizedlist>
            <listitem>
                <para>
                    <link linkend="zend.gdata.calendar">Google Calendar</link>
                    is a popular online calendar application.
                </para>
            </listitem>

            <listitem>
                <para>
                    <link linkend="zend.gdata.spreadsheets">Google Spreadsheets</link>
                    provides an online collaborative spreadsheets tool which
                    can be used as a simple data store for your applications.
                </para>
            </listitem>

            <listitem>
                <para>
                    <link linkend="zend.gdata.docs">Google Documents List</link>
                    provides an online list of all spreadsheets, word processing documents,
                    and presentations stored in a Google account.
                </para>
            </listitem>

            <listitem>
                <para>
                    <link linkend="zend.gdata.gapps">Google Provisioning</link>
                    provides the ability to create, retrieve, update, and
                    delete user accounts, nicknames, groups, and email lists on a
                    Google Apps hosted domain.
                </para>
            </listitem>

            <listitem>
                <para>
                    <link linkend="zend.gdata.photos">Picasa Web Albums</link>
                    provides an online photo sharing application.
                </para>
            </listitem>
            
            <listitem>
                <para>
                    <link linkend="zend.gdata.analytics">Google Analytics</link>
                    is a visitor statistics application.
                </para>
            </listitem>

            <listitem>
                <para>
                    <ulink
                        url="http://code.google.com/apis/blogger/developers_guide_php.html">Google
                        Blogger</ulink> is a popular Internet provider of
                    "push-button publishing" and syndication.
                </para>
            </listitem>

            <listitem>
                <para>
                    Google CodeSearch
                    allows you to search public source code from many projects.
                </para>
            </listitem>

            <listitem>
                <para>
                    Google Notebook
                    allows you to view public Notebook content.
                </para>
            </listitem>
        </itemizedlist>
    </para>

    <note>
        <title>Unsupported services</title>

        <para>
            <classname>Zend_Gdata</classname> does not provide an interface to any other Google
            service, such as Search, Gmail, Translation, or Maps.
            Only services that support the Google Data <acronym>API</acronym> are supported.
        </para>
    </note>

    <sect2 id="zend.gdata.introduction.structure">
        <title>Structure of Zend_Gdata</title>

        <para>
            <classname>Zend_Gata</classname> is composed of several types of classes:

            <itemizedlist>
                <listitem>
                    <para>
                        Service classes - inheriting from <classname>Zend_Gdata_App</classname>.
                        These also include other classes such as <classname>Zend_Gdata</classname>,
                        <classname>Zend_Gdata_Spreadsheets</classname>, etc. These classes enable
                        interacting with APP or GData services and provide the
                        ability to retrieve feeds, retrieve entries, post
                        entries, update entries and delete entries.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        Query classes - inheriting from <classname>Zend_Gdata_Query</classname>.
                        These also include other classes for specific services,
                        such as <classname>Zend_Gdata_Spreadsheets_ListQuery</classname> and
                        <classname>Zend_Gdata_Spreadsheets_CellQuery</classname>. Query classes
                        provide methods used to construct a query for data
                        to be retrieved from GData services. Methods include
                        getters and setters like <methodname>setUpdatedMin()</methodname>,
                        <methodname>setStartIndex()</methodname>, and
                        <methodname>getPublishedMin()</methodname>. The query classes also
                        have a method to generate a <acronym>URL</acronym> representing the
                        constructed query -- <methodname>getQueryUrl()</methodname>.
                        Alternatively, the query string component of the <acronym>URL</acronym>
                        can be retrieved used the <methodname>getQueryString()</methodname>
                        method.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        Feed classes - inheriting from <classname>Zend_Gdata_App_Feed</classname>.
                        These also include other classes such as
                        <classname>Zend_Gdata_Feed</classname>,
                        <classname>Zend_Gdata_Spreadsheets_SpreadsheetFeed</classname>,
                        and <classname>Zend_Gdata_Spreadsheets_ListFeed</classname>.
                        These classes represent feeds of entries retrieved
                        from services. They are primarily used to retrieve
                        data returned from services.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        Entry classes - inheriting from <classname>Zend_Gdata_App_Entry</classname>.
                        These also include other classes such as
                        <classname>Zend_Gdata_Entry</classname>, and
                        <classname>Zend_Gdata_Spreadsheets_ListEntry</classname>.
                        These classes represent entries retrieved from
                        services or used for constructing data to send to
                        services. In addition to being able to set the
                        properties of an entry (such as the spreadsheet cell
                        value), you can use an entry object to send update
                        or delete requests to a service. For example,
                        you can call <command>$entry->save()</command> to save
                        changes made to an entry back to service from which
                        the entry initiated, or <command>$entry->delete()</command>
                        to delete an entry from the server.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        Other Data model classes - inheriting from
                        <classname>Zend_Gdata_App_Extension</classname>. These include classes such
                        as <classname>Zend_Gdata_App_Extension_Title</classname> (representing the
                        atom:title <acronym>XML</acronym> element),
                        <classname>Zend_Gdata_Extension_When</classname>
                        (representing the gd:when <acronym>XML</acronym> element used by the
                        GData Event "Kind"), and
                        <classname>Zend_Gdata_Extension_Cell</classname> (representing the gs:cell
                        <acronym>XML</acronym> element used by Google Spreadsheets). These
                        classes are used purely to store the data retrieved
                        back from services and for constructing data to be
                        sent to services. These include getters and setters
                        such as
                        <methodname>setText()</methodname> to set the child text
                        node of an element, <methodname>getText()</methodname> to retrieve
                        the text node of an element, <methodname>getStartTime()</methodname>
                        to retrieve the start time attribute of a When element,
                        and other similiar methods.
                        The data model classes also include methods such as
                        <methodname>getDOM()</methodname> to retrieve a DOM representation
                        of the element and all children and
                        <methodname>transferFromDOM()</methodname> to construct a data
                        model representation of a DOM tree.
                    </para>
                </listitem>
            </itemizedlist>
        </para>
    </sect2>

    <sect2 id="zend.gdata.introduction.services">
        <title>Interacting with Google Services</title>

        <para>
            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 <classname>Zend_Gdata</classname> component, you need to use
            the service classes such as <classname>Zend_Gdata_App</classname>,
            <classname>Zend_Gdata</classname>, <classname>Zend_Gdata_Spreadsheets</classname>, etc.
            These service classes provide methods to retrieve data from services as feeds, insert
            new entries into feeds, update entries, and delete entries.
        </para>

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

    <sect2 id="zend.gdata.introduction.magicfactory">
        <title>Obtaining instances of Zend_Gdata classes</title>

        <para>
            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:
            <filename>Zend/Gdata/Spreadsheets/Extension/...</filename> and, as a result
            of this, are named
            <classname>Zend_Gdata_Spreadsheets_Extension_...</classname>.
            This causes a lot of typing if you're trying to construct a new
            instance of a spreadsheet cell element!
        </para>

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

        <programlisting language="php"><![CDATA[
$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
]]></programlisting>

        <para>
            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.
        </para>
    </sect2>

    <sect2 id="zend.gdata.introduction.authentication">
        <title>Google Data Client Authentication</title>

        <para>
            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:
            <link linkend="zend.gdata.authsub">AuthSub</link> and
            <link linkend="zend.gdata.clientlogin">ClientLogin</link>.
            <classname>Zend_Gdata</classname> offers class interfaces for both of these methods.
        </para>

        <para>
            Most other types of queries against Google Data services do not
            require authentication.
        </para>
    </sect2>

    <sect2 id="zend.gdata.introduction.dependencies">
        <title>Dependencies</title>

        <para>
            <classname>Zend_Gdata</classname> makes use of
            <link linkend="zend.http.client">Zend_Http_Client</link> to send
            requests to google.com and fetch results. The response to most
            Google Data requests is returned as a subclass of the
            <classname>Zend_Gdata_App_Feed</classname> or
            <classname>Zend_Gdata_App_Entry</classname> classes.
        </para>

        <para>
            <classname>Zend_Gdata</classname> assumes your <acronym>PHP</acronym> application is
            running on a host that has a direct connection to the Internet.
            The <classname>Zend_Gdata</classname> client operates by contacting Google Data servers.
        </para>
    </sect2>

    <sect2 id="zend.gdata.introduction.creation">
        <title>Creating a new Gdata client</title>

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

        <para>
            The single optional parameter to the <classname>Zend_Gdata_App</classname> constructor
            is an instance of
            <link linkend="zend.http.client">Zend_Http_Client</link>.
            If you don't pass this parameter, <classname>Zend_Gdata</classname> creates a default
            <classname>Zend_Http_Client</classname> object, which will not have associated
            credentials to access private feeds. Specifying the
            <classname>Zend_Http_Client</classname> object also allows you to
            pass configuration options to that client object.
        </para>

        <programlisting language="php"><![CDATA[
$client = new Zend_Http_Client();
$client->setConfig( ...options... );

$gdata = new Zend_Gdata($client);
]]></programlisting>

        <para>
            Beginning with Zend Framework 1.7, support has been added for
            protocol versioning. This allows the client and server to support
            new features while maintaining backwards compatibility. While most
            services will manage this for you, if you create a <classname>Zend_Gdata</classname>
            instance directly (as opposed to one of its subclasses), you may
            need to specify the desired protocol version to access certain
            server functionality.
        </para>

        <programlisting language="php"><![CDATA[
$client = new Zend_Http_Client();
$client->setConfig( ...options... );

$gdata = new Zend_Gdata($client);
$gdata->setMajorProtocolVersion(2);
$gdata->setMinorProtocolVersion(null);
]]></programlisting>

        <para>
            Also see the sections on authentication for methods to
            create an authenticated <classname>Zend_Http_Client</classname> object.
        </para>
    </sect2>

    <sect2 id="zend.gdata.introduction.parameters">
        <title>Common Query Parameters</title>

        <para>
            You can specify parameters to customize queries with <classname>Zend_Gdata</classname>.
            Query parameters are specified using subclasses of
            <classname>Zend_Gdata_Query</classname>. The <classname>Zend_Gdata_Query</classname>
            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.
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    The <property>q</property> parameter specifies a full-text
                    query. The value of the parameter is a string.
                </para>

                <para>
                    Set this parameter with the <methodname>setQuery()</methodname>
                    function.
                </para>
            </listitem>

            <listitem>
                <para>
                    The <property>alt</property> parameter specifies the feed type.
                    The value of the parameter can be <property>atom</property>,
                    <property>rss</property>, <property>json</property>,
                    or <property>json-in-script</property>.
                    If you don't specify this parameter, the default feed type
                    is <property>atom</property>. NOTE: Only the output of the
                    atom feed format can be processed using
                    <classname>Zend_Gdata</classname>.
                    The <classname>Zend_Http_Client</classname> could be used to retrieve
                    feeds in other formats, using query <acronym>URL</acronym>s generated by the
                    <classname>Zend_Gdata_Query</classname> class and its subclasses.
                </para>

                <para>
                    Set this parameter with the <methodname>setAlt()</methodname>
                    function.
                </para>
            </listitem>

            <listitem>
                <para>
                    The <property>maxResults</property> parameter limits the number
                    of entries in the feed. The value of the parameter is
                    an integer. The number of entries returned in the feed
                    will not exceed this value.
                </para>

                <para>
                    Set this parameter with the <methodname>setMaxResults()</methodname> function.
                </para>
            </listitem>

            <listitem>
                <para>
                    The <property>startIndex</property> parameter specifies the
                    ordinal number of the first entry returned in the feed.
                    Entries before this number are skipped.
                </para>

                <para>
                    Set this parameter with the <methodname>setStartIndex()</methodname>
                    function.
                </para>
            </listitem>

            <listitem>
                <para>
                    The <property>updatedMin</property> and <property>updatedMax</property>
                    parameters specify bounds on the entry date.
                    If you specify a value for <property>updatedMin</property>,
                    no entries that were updated earlier than the date
                    you specify are included in the feed. Likewise
                    no entries updated after the date specified by
                    <property>updatedMax</property> are included.
                </para>

                <para>
                    You can use numeric timestamps, or a variety of
                    date/time string representations as the value for
                    these parameters.
                </para>

                <para>
                    Set this parameter with the <methodname>setUpdatedMin()</methodname>
                    and <methodname>setUpdatedMax()</methodname> functions.
                </para>
            </listitem>
        </itemizedlist>

        <para>
            There is a <methodname>get*()</methodname> function for each
            <methodname>set*()</methodname> function.
        </para>

        <programlisting language="php"><![CDATA[
$query = new Zend_Gdata_Query();
$query->setMaxResults(10);
echo $query->getMaxResults();   // returns 10
]]></programlisting>

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

        <programlisting language="php"><![CDATA[
$query = new Zend_Gdata_Query();
$query->maxResults = 10;
echo $query->maxResults;        // returns 10
]]></programlisting>

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

        <programlisting language="php"><![CDATA[
$query = new Zend_Gdata_Query();
$query->maxResults = 10;
// ...get feed...

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

    <sect2 id="zend.gdata.introduction.getfeed">
        <title>Fetching a Feed</title>

        <para>
            Use the <methodname>getFeed()</methodname> function to retrieve
            a feed from a specified <acronym>URI</acronym>.
            This function returns an instance of class specified
            as the second argument to getFeed, which defaults to
            <classname>Zend_Gdata_Feed</classname>.
        </para>

        <programlisting language="php"><![CDATA[
$gdata = new Zend_Gdata();
$query = new Zend_Gdata_Query(
        'http://www.blogger.com/feeds/blogID/posts/default');
$query->setMaxResults(10);
$feed = $gdata->getFeed($query);
]]></programlisting>

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

    <sect2 id="zend.gdata.introduction.paging">
        <title>Working with Multi-page Feeds</title>

        <para>
            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
            <methodname>getLink('next')</methodname>. The following example shows how to
            retrieve the next page of a feed:
        </para>

        <programlisting language="php"><![CDATA[
function getNextPage($feed) {
    $nextURL = $feed->getLink('next');
    if ($nextURL !== null) {
        return $gdata->getFeed($nextURL);
    } else {
        return null;
    }
}
]]></programlisting>

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

        <programlisting language="php"><![CDATA[
$gdata = new Zend_Gdata();
$query = new Zend_Gdata_Query(
        'http://www.blogger.com/feeds/blogID/posts/default');
$feed = $gdata->retrieveAllEntriesForFeed($gdata->getFeed($query));
]]></programlisting>

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

    <sect2 id="zend.gdata.introduction.usefeedentry">
        <title>Working with Data in Feeds and Entries</title>

        <para>
            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:
        </para>

        <programlisting language="php"><![CDATA[
$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();
}
]]></programlisting>
    </sect2>

    <sect2 id="zend.gdata.introduction.updateentry">
        <title>Updating Entries</title>

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

        <programlisting language="php"><![CDATA[
$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;
}
]]></programlisting>
    </sect2>

    <sect2 id="zend.gdata.introduction.post">
        <title>Posting Entries to Google Servers</title>

        <para>
            The <classname>Zend_Gdata</classname> object has a function
            <methodname>insertEntry()</methodname> with which you can upload data to save
            new entries to Google Data services.
        </para>

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

        <para>
            Alternatively, you could construct the <acronym>XML</acronym> structure for an entry
            as a string and pass the string to the <methodname>insertEntry()</methodname>
            function.
        </para>

        <programlisting language="php"><![CDATA[
$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;
]]></programlisting>

        <para>
            To post entries, you must be using an authenticated
            <classname>Zend_Http_Client</classname> that you created using the
            <classname>Zend_Gdata_AuthSub</classname> or
            <classname>Zend_Gdata_ClientLogin</classname> classes.
        </para>
    </sect2>

    <sect2 id="zend.gdata.introduction.delete">
        <title>Deleting Entries on Google Servers</title>

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

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

        <programlisting language="php"><![CDATA[
$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);
}
]]></programlisting>

        <para>
            To delete entries, you must be using an authenticated
            <classname>Zend_Http_Client</classname> that you created using the
            <classname>Zend_Gdata_AuthSub</classname> or
            <classname>Zend_Gdata_ClientLogin</classname> classes.
        </para>
    </sect2>
</sect1>