repo_zf1/documentation/manual/en/module_specs/Zend_Feed_Writer.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect1 id="zend.feed.writer">
    <title>Zend_Feed_Writer</title>

    <sect2 id="zend.feed.writer.introduction">
        <title>Introduction</title>

        <para>
            <classname>Zend_Feed_Writer</classname> is the sibling component to
            <classname>Zend_Feed_Reader</classname> responsible for generating feeds for output. It
            supports the Atom 1.0 specification (RFC 4287) and <acronym>RSS</acronym> 2.0 as
            specified by the <acronym>RSS</acronym> Advisory Board (<acronym>RSS</acronym> 2.0.11).
            It does not deviate from these standards. It does, however, offer a simple Extension
            system which allows for any extension and module for either of these two specifications
            to be implemented if they are not provided out of the box.
        </para>

        <para>
            In many ways, <classname>Zend_Feed_Writer</classname> is the inverse of
            <classname>Zend_Feed_Reader</classname>. Where <classname>Zend_Feed_Reader</classname>
            focuses on providing an easy to use architecture fronted by getter methods,
            <classname>Zend_Feed_Writer</classname> is fronted by similarly named setters or
            mutators. This ensures the <acronym>API</acronym> won't pose a learning curve to anyone
            familiar with <classname>Zend_Feed_Reader</classname>.
        </para>

        <para>
            As a result of this design, the rest may even be obvious. Behind the scenes, data set on
            any <classname>Zend_Feed_Writer</classname> Data Container object is translated at render time onto a
            DOMDocument object using the necessary feed elements. For each
            supported feed type there is both an Atom 1.0 and <acronym>RSS</acronym> 2.0 renderer.
            Using a DOMDocument class rather than a templating solution has numerous advantages,
            the most obvious being the ability to export the DOMDocument for
            additional processing and relying on <acronym>PHP</acronym> <acronym>DOM</acronym> for
            correct and valid rendering.
        </para>

        <para>
            As with <classname>Zend_Feed_Reader</classname>, <classname>Zend_Feed_Writer</classname>
            is a standalone replacement for <classname>Zend_Feed</classname>'s Builder architecture
            and is not compatible with those classes.
        </para>
    </sect2>

    <sect2 id="zend.feed.writer.architecture">
        <title>Architecture</title>

        <para>
            The architecture of <classname>Zend_Feed_Writer</classname> is very simple. It has two
            core sets of classes: data containers and renderers.
        </para>

        <para>
            The containers include the <classname>Zend_Feed_Writer_Feed</classname> and
            <classname>Zend_Feed_Writer_Entry</classname> classes. The Entry classes can be attached
            to any Feed class. The sole purpose of these containers is to collect data about the
            feed to generate using a simple interface of setter methods. These methods perform some
            data validity testing. For example, it will validate any passed <acronym>URI</acronym>s,
            dates, etc. These checks are not tied to any of the feed standards definitions. The container
            objects also contain methods to allow for fast rendering and export of the final feed,
            and these can be reused at will.
        </para>
        
        <para>
            In addition to the main data container classes, there are two additional Atom 2.0 specific
            classes. <classname>Zend_Feed_Writer_Source</classname> and <classname>
            Zend_Feed_Writer_Deleted</classname>. The former implements Atom 2.0 source elements which
            carry source feed metadata for a specific entry within an aggregate feed (i.e. the current feed
            is not the entry's original source). The latter implements the Atom Tombstones RFC allowing
            feeds to carry references to entries which have been deleted.
        </para>

        <para>
            While there are two main data container types, there are four renderers - two matching container
            renderers per supported feed type. Each renderer accepts a container, and based on its
            content attempts to generate valid feed markup. If the renderer is unable to generate valid
            feed markup, perhaps due to the container missing an obligatory data point, it will report this
            by throwing an <classname>Exception</classname>. While it is possible to ignore
            <classname>Exception</classname>s, this removes the default safeguard of ensuring you
            have sufficient data set to render a wholly valid feed.
        </para>
        
        <para>
            To explain this more clearly, you may construct a set of data containers for a feed where
            there is a Feed container, into which has been added some Entry containers and a Deleted
            container. This forms a data hierarchy resembling a normal feed. When rendering is performed,
            this hierarchy has its pieces passed to relevant renderers and the partial feeds (all DOMDocuments)
            are then pieced together to create a complete feed. In the case of Source or Deleted (Tomestone)
            containers, these are rendered only for Atom 2.0 and ignored for RSS.
        </para>

        <para>
            Due to the system being divided between data containers and renderers, it can make
            Extensions somewhat interesting. A typical Extension offering namespaced feed and entry
            level elements, must itself reflect the exact same architecture, i.e. offer feed and
            entry level data containers, and matching renderers. There is, fortunately, no complex
            integration work required since all Extension classes are simply registered and
            automatically used by the core classes. We'll meet Extensions in more detail at the end
            of this section.
        </para>
    </sect2>

    <sect2 id="zend.feed.writer.getting.started">
        <title>Getting Started</title>

        <para>
            Using <classname>Zend_Feed_Writer</classname> is as simple as setting data and
            triggering the renderer. Here is an example to generate a minimal Atom 1.0 feed.
            As this demonstrates, each feed/entry uses a separate data container.
        </para>

        <programlisting language="php"><![CDATA[
/**
 * Create the parent feed
 */
$feed = new Zend_Feed_Writer_Feed;
$feed->setTitle('Paddy\'s Blog');
$feed->setLink('http://www.example.com');
$feed->setFeedLink('http://www.example.com/atom', 'atom');
$feed->addAuthor(array(
    'name'  => 'Paddy',
    'email' => 'paddy@example.com',
    'uri'   => 'http://www.example.com',
));
$feed->setDateModified(time());
$feed->addHub('http://pubsubhubbub.appspot.com/');

/**
 * Add one or more entries. Note that entries must
 * be manually added once created.
 */
$entry = $feed->createEntry();
$entry->setTitle('All Your Base Are Belong To Us');
$entry->setLink('http://www.example.com/all-your-base-are-belong-to-us');
$entry->addAuthor(array(
    'name'  => 'Paddy',
    'email' => 'paddy@example.com',
    'uri'   => 'http://www.example.com',
));
$entry->setDateModified(time());
$entry->setDateCreated(time());
$entry->setDescription('Exposing the difficultly of porting games to English.');
$entry->setContent(
    'I am not writing the article. The example is long enough as is ;).'
);
$feed->addEntry($entry);

/**
 * Render the resulting feed to Atom 1.0 and assign to $out.
 * You can substitute "atom" with "rss" to generate an RSS 2.0 feed.
 */
$out = $feed->export('atom');
]]></programlisting>

        <para>
            The output rendered should be as follows:
        </para>

        <programlisting language="xml"><![CDATA[
<?xml version="1.0" encoding="utf-8"?>
<feed xmlns="http://www.w3.org/2005/Atom">
    <title type="text">Paddy's Blog</title>
    <subtitle type="text">Writing about PC Games since 176 BC.</subtitle>
    <updated>2009-12-14T20:28:18+00:00</updated>
    <generator uri="http://framework.zend.com" version="1.10.0alpha">
        Zend_Feed_Writer
    </generator>
    <link rel="alternate" type="text/html" href="http://www.example.com"/>
    <link rel="self" type="application/atom+xml"
        href="http://www.example.com/atom"/>
    <id>http://www.example.com</id>
    <author>
        <name>Paddy</name>
        <email>paddy@example.com</email>
        <uri>http://www.example.com</uri>
    </author>
    <link rel="hub" href="http://pubsubhubbub.appspot.com/"/>
    <entry>
        <title type="html"><![CDATA[All Your Base Are Belong To
            Us]]]]><![CDATA[></title>
        <summary type="html">
            <![CDATA[Exposing the difficultly of porting games to
                English.]]]]><![CDATA[>
        </summary>
        <published>2009-12-14T20:28:18+00:00</published>
        <updated>2009-12-14T20:28:18+00:00</updated>
        <link rel="alternate" type="text/html"
             href="http://www.example.com/all-your-base-are-belong-to-us"/>
        <id>http://www.example.com/all-your-base-are-belong-to-us</id>
        <author>
            <name>Paddy</name>
            <email>paddy@example.com</email>
            <uri>http://www.example.com</uri>
        </author>
        <content type="html">
            <![CDATA[I am not writing the article.
                     The example is long enough as is ;).]]]]><![CDATA[>
        </content>
    </entry>
</feed>
]]></programlisting>

        <para>
            This is a perfectly valid Atom 1.0 example. It should be noted that omitting an
            obligatory point of data, such as a title, will trigger an
            <classname>Exception</classname> when rendering as Atom 1.0. This will differ for
            <acronym>RSS</acronym> 2.0 since a title may be omitted so long as a description is
            present. This gives rise to Exceptions that differ between the two standards depending
            on the renderer in use. By design, <classname>Zend_Feed_Writer</classname> will not
            render an invalid feed for either standard unless the end-user deliberately elects to
            ignore all Exceptions. This built in safeguard was added to ensure users without
            in-depth knowledge of the relevant specifications have a bit less to worry about.
        </para>
    </sect2>

    <sect2 id="zend.feed.writer.setting.feed.data.points">
        <title>Setting Feed Data Points</title>

        <para>
            Before you can render a feed, you must first setup the data necessary for
            the feed being rendered. This utilises a simple setter style <acronym>API</acronym>
            which doubles as an initial method for validating the data being set. By design, the
            <acronym>API</acronym> closely matches that for <classname>Zend_Feed_Reader</classname>
            to avoid undue confusion and uncertainty.
        </para>
        
        <note>
            <para>Users have commented that the lack of a simple array based notation for input data
            gives rise to lengthy tracts of code. This will be addressed in a future release.</para>
        </note>
        
        <para>
            <classname>Zend_Feed_Writer</classname> offers this <acronym>API</acronym> via its data
            container classes <classname>Zend_Feed_Writer_Feed</classname> and
            <classname>Zend_Feed_Writer_Entry</classname> (not to mention the Atom 2.0 specific
            and Extension classes). These classes merely store
            all feed data in a type-agnostic manner, meaning you may reuse any data
            container with any renderer without requiring additional work. Both classes
            are also amenable to Extensions, meaning that an Extension may define its own
            container classes which are registered to the base container classes as extensions, and
            are checked when any method call triggers the base container's
            <methodname>__call()</methodname> method.
        </para>

        <para>
            Here's a summary of the Core <acronym>API</acronym> for Feeds. You should note it
            comprises not only the basic <acronym>RSS</acronym> and Atom standards, but also
            accounts for a number of included Extensions bundled with
            <classname>Zend_Feed_Writer</classname>. The naming of these
            Extension sourced methods remain fairly generic - all Extension
            methods operate at the same level as the Core <acronym>API</acronym> though we do allow
            you to retrieve any specific Extension object separately if required.
        </para>
        
        <para>
            The Feed Level API for data is contained in <classname>Zend_Feed_Writer_Feed</classname>.
            In addition to the API detailed below, the class also implements the <classname>Countable
            </classname> and <classname>Iterator</classname> interfaces.
        </para>

        <table>
            <title>Feed Level API Methods</title>

            <tgroup cols="2">
                <tbody>
                    <row>
                        <entry><methodname>setId()</methodname></entry>

                        <entry>
                            Set a unique ID associated with this feed. For Atom 1.0
                            this is an atom:id element, whereas for <acronym>RSS</acronym> 2.0 it
                            is added as a guid element. These are optional so long as a link is
                            added, i.e. the link is set as the ID.
                        </entry>
                    </row>

                    <row>
                        <entry><methodname>setTitle()</methodname></entry>
                        <entry>Set the title of the feed.</entry>
                    </row>

                    <row>
                        <entry><methodname>setDescription()</methodname></entry>
                        <entry>Set the text description of the feed.</entry>
                    </row>

                    <row>
                        <entry><methodname>setLink()</methodname></entry>

                        <entry>
                            Set a <acronym>URI</acronym> to the <acronym>HTML</acronym> website
                            containing the same or
                            similar information as this feed (i.e. if the feed is from a blog,
                            it should provide the blog's <acronym>URI</acronym> where the
                            <acronym>HTML</acronym> version of the entries can be read).
                        </entry>
                    </row>

                    <row>
                        <entry><methodname>setFeedLinks()</methodname></entry>

                        <entry>
                            Add a link to an <acronym>XML</acronym> feed, whether the feed being
                            generated or an alternate <acronym>URI</acronym> pointing to the same
                            feed but in a different format. At a minimum, it is recommended to
                            include a link to the feed being generated so it has an identifiable
                            final <acronym>URI</acronym> allowing a client to track its location
                            changes without necessitating constant redirects. The parameter is an
                            array of arrays, where each sub-array contains the keys "type" and
                            "uri". The type should be one of "atom", "rss", or "rdf".
                        </entry>
                    </row>

                    <row>
                        <entry><methodname>addAuthors()</methodname></entry>

                        <entry>
                            Sets the data for authors. The parameter is an array of arrays
                            where each sub-array may contain the keys "name", "email" and
                            "uri". The "uri" value is only applicable for Atom feeds since
                            <acronym>RSS</acronym> contains no facility to show it. For
                            <acronym>RSS</acronym> 2.0, rendering will create two elements - an
                            author element containing the email reference with the name in brackets,
                            and a Dublin Core creator element only containing the name.
                        </entry>
                    </row>

                    <row>
                        <entry><methodname>addAuthor()</methodname></entry>

                        <entry>
                            Sets the data for a single author following the same
                            array format as described above for a single sub-array.
                        </entry>
                    </row>

                    <row>
                        <entry><methodname>setDateCreated()</methodname></entry>

                        <entry>
                            Sets the date on which this feed was created. Generally
                            only applicable to Atom where it represents the date the resource
                            described by an Atom 1.0 document was created. The expected parameter
                            may be a <acronym>UNIX</acronym> timestamp or a
                            <classname>Zend_Date</classname> object.
                        </entry>
                    </row>

                    <row>
                        <entry><methodname>setDateModified()</methodname></entry>

                        <entry>
                            Sets the date on which this feed was last modified. The expected
                            parameter may be a <acronym>UNIX</acronym> timestamp or a
                            <classname>Zend_Date</classname> object.
                        </entry>
                    </row>

                    <row>
                        <entry><methodname>setLanguage()</methodname></entry>

                        <entry>
                            Sets the language of the feed. This will be omitted unless set.
                        </entry>
                    </row>

                    <row>
                        <entry><methodname>getGenerator()</methodname></entry>

                        <entry>
                            Allows the setting of a generator. The parameter should be an
                            array containing the keys "name", "version" and "uri". If omitted
                            a default generator will be added referencing
                            <classname>Zend_Feed_Writer</classname>, the current Zend Framework
                            version and the Framework's <acronym>URI</acronym>.
                        </entry>
                    </row>

                    <row>
                        <entry><methodname>setCopyright()</methodname></entry>
                        <entry>Sets a copyright notice associated with the feed.</entry>
                    </row>

                    <row>
                        <entry><methodname>addHubs()</methodname></entry>

                        <entry>
                            Accepts an array of Pubsubhubbub Hub Endpoints to be rendered in
                            the feed as Atom links so that PuSH Subscribers may subscribe to
                            your feed. Note that you must implement a Pubsubhubbub Publisher in
                            order for real-time updates to be enabled. A Publisher may be
                            implemented using
                            <classname>Zend_Feed_Pubsubhubbub_Publisher</classname>.
                            The method <methodname>addHub()</methodname> allows adding
                            a single hub at a time.
                        </entry>
                    </row>

                    <row>
                        <entry><methodname>addCategories()</methodname></entry>

                        <entry>
                            Accepts an array of categories for rendering, where each element is
                            itself an array whose possible keys include "term", "label" and
                            "scheme". The "term" is a typically a category name suitable for
                            inclusion in a <acronym>URI</acronym>. The "label" may be a human
                            readable category name supporting special characters (it is HTML encoded
                            during rendering) and is a required key. The "scheme" (called the domain
                            in <acronym>RSS</acronym>) is optional but must be a valid
                            <acronym>URI</acronym>.
                            The method <methodname>addCategory()</methodname> allows adding
                            a single category at a time.
                        </entry>
                    </row>
                    
                    <row>
                        <entry><methodname>createEntry()</methodname></entry>
                        <entry>Returns a new instance of <classname>Zend_Feed_Writer_Entry
                        </classname>. This is the Entry level data container. New entries
                        are not automatically assigned to the current feed, so you
                        must explicitly call <methodname>addEntry()</methodname>
                        to add the entry for rendering.</entry>
                    </row>
                    
                    <row>
                        <entry><methodname>addEntry()</methodname></entry>
                        <entry>Adds an instance of <classname>Zend_Feed_Writer_Entry
                        </classname> to the current feed container for rendering.</entry>
                    </row>
                    
                    <row>
                        <entry><methodname>createTombstone()</methodname></entry>
                        <entry>Returns a new instance of <classname>Zend_Feed_Writer_Deleted
                        </classname>. This is the Atom 2.0 Tombstone level data container. New entries
                        are not automatically assigned to the current feed, so you
                        must explicitly call <methodname>addTombstone()</methodname>
                        to add the deleted entry for rendering.</entry>
                    </row>
                    
                    <row>
                        <entry><methodname>addTombstone()</methodname></entry>
                        <entry>Adds an instance of <classname>Zend_Feed_Writer_Deleted
                        </classname> to the current feed container for rendering.</entry>
                    </row>
                    
                    <row>
                        <entry><methodname>removeEntry()</methodname></entry>
                        <entry>Accepts a parameter indicating an array index of the
                        entry to remove from the feed.</entry>
                    </row>
                    
                    <row>
                        <entry><methodname>export()</methodname></entry>
                        <entry>Exports the entire data hierarchy to an XML feed. The method
                        has two parameters. The first is the feed type, one of "atom"
                        or "rss". The second is an optional boolean to set whether
                        Exceptions are thrown. The default is TRUE.</entry>
                    </row>
                </tbody>
            </tgroup>
        </table>
        
        <note>
            <para>In addition to these setters, there are also matching getters to retrieve data from the
            Entry data container.</para>
        </note>
        
        <!-- remaining feed stuff -->
        
    </sect2>

    <sect2 id="zend.feed.writer.setting.entry.data.points">
        <title>Setting Entry Data Points</title>

        <para>
            Here's a summary of the Core <acronym>API</acronym> for Entries and Items. You should
            note it comprises not only the basic <acronym>RSS</acronym> and Atom standards, but
            also accounts for a number of included Extensions bundled with
            <classname>Zend_Feed_Writer</classname>. The naming of these
            Extension sourced methods remain fairly generic - all Extension
            methods operate at the same level as the Core <acronym>API</acronym> though we do allow
            you to retrieve any specific Extension object separately if required.
        </para>
        
        <para>
            The Entry Level API for data is contained in <classname>Zend_Feed_Writer_Entry</classname>.
        </para>

        <table>
            <title>Entry Level API Methods</title>

            <tgroup cols="2">
                <tbody>
                    <row>
                        <entry><methodname>setId()</methodname></entry>

                        <entry>
                            Set a unique ID associated with this entry. For Atom 1.0
                            this is an atom:id element, whereas for <acronym>RSS</acronym> 2.0 it is
                            added as a guid element. These are optional so long as a link is
                            added, i.e. the link is set as the ID.
                        </entry>
                    </row>

                    <row>
                        <entry><methodname>setTitle()</methodname></entry>
                        <entry>Set the title of the entry.</entry>
                    </row>

                    <row>
                        <entry><methodname>setDescription()</methodname></entry>
                        <entry>Set the text description of the entry.</entry>
                    </row>
                    
                    <row>
                        <entry><methodname>setContent()</methodname></entry>
                        <entry>Set the content of the entry.</entry>
                    </row>

                    <row>
                        <entry><methodname>setLink()</methodname></entry>

                        <entry>
                            Set a <acronym>URI</acronym> to the <acronym>HTML</acronym> website
                            containing the same or
                            similar information as this entry (i.e. if the feed is from a blog,
                            it should provide the blog article's <acronym>URI</acronym> where the
                            <acronym>HTML</acronym> version of the entry can be read).
                        </entry>
                    </row>

                    <row>
                        <entry><methodname>setFeedLinks()</methodname></entry>

                        <entry>
                            Add a link to an <acronym>XML</acronym> feed, whether the feed being
                            generated or an alternate <acronym>URI</acronym> pointing to the same
                            feed but in a different format. At a minimum, it is recommended to
                            include a link to the feed being generated so it has an identifiable
                            final <acronym>URI</acronym> allowing a client to track its location
                            changes without necessitating constant redirects. The parameter is an
                            array of arrays, where each sub-array contains the keys "type" and
                            "uri". The type should be one of "atom", "rss", or "rdf". If a type is
                            omitted, it defaults to the type used when rendering the feed.
                        </entry>
                    </row>

                    <row>
                        <entry><methodname>addAuthors()</methodname></entry>

                        <entry>
                            Sets the data for authors. The parameter is an array of arrays
                            where each sub-array may contain the keys "name", "email" and
                            "uri". The "uri" value is only applicable for Atom feeds since
                            <acronym>RSS</acronym> contains no facility to show it. For
                            <acronym>RSS</acronym> 2.0, rendering will create two elements - an
                            author element containing the email reference with the name in brackets,
                            and a Dublin Core creator element only containing the name.
                        </entry>
                    </row>

                    <row>
                        <entry><methodname>addAuthor()</methodname></entry>

                        <entry>
                            Sets the data for a single author following the same
                            format as described above for a single sub-array.
                        </entry>
                    </row>

                    <row>
                        <entry><methodname>setDateCreated()</methodname></entry>

                        <entry>
                            Sets the date on which this feed was created. Generally
                            only applicable to Atom where it represents the date the resource
                            described by an Atom 1.0 document was created. The expected parameter
                            may be a <acronym>UNIX</acronym> timestamp or a
                            <classname>Zend_Date</classname> object. If omitted, the date
                            used will be the current date and time.
                        </entry>
                    </row>

                    <row>
                        <entry><methodname>getDateModified()</methodname></entry>

                        <entry>
                            Sets the date on which this feed was last modified. The expected
                            parameter may be a <acronym>UNIX</acronym> timestamp or a
                            <classname>Zend_Date</classname> object. If omitted, the date
                            used will be the current date and time.
                        </entry>
                    </row>

                    <row>
                        <entry><methodname>setCopyright()</methodname></entry>
                        <entry>Sets a copyright notice associated with the feed.</entry>
                    </row>

                    <row>
                        <entry><methodname>setCategories()</methodname></entry>

                        <entry>
                            Accepts an array of categories for rendering, where each element is
                            itself an array whose possible keys include "term", "label" and
                            "scheme". The "term" is a typically a category name suitable for
                            inclusion in a <acronym>URI</acronym>. The "label" may be a human
                            readable category name supporting special characters (it is encoded
                            during rendering) and is a required key. The "scheme" (called the domain
                            in <acronym>RSS</acronym>) is optional but must be a valid
                            <acronym>URI</acronym>.
                        </entry>
                    </row>
                    
                    <row>
                        <entry><methodname>setCommentCount()</methodname></entry>

                        <entry>
                            Sets the number of comments associated with this entry. Rendering
                            differs between <acronym>RSS</acronym> and Atom 2.0 depending
                            on the element/attribute needed.
                        </entry>
                    </row>
                    
                    <row>
                        <entry><methodname>setCommentLink()</methodname></entry>

                        <entry>
                            Seta a link to a HTML page containing comments associated with this entry.
                        </entry>
                    </row>
                    
                    <row>
                        <entry><methodname>setCommentFeedLink()</methodname></entry>

                        <entry>
                            Sets a link to a XML feed containing comments associated with this entry.
                            The parameter is an array containing the keys "uri" and "type", where
                            the type is one of "rdf", "rss" or "atom".
                        </entry>
                    </row>
                    
                    <row>
                        <entry><methodname>setCommentFeedLinks()</methodname></entry>

                        <entry>
                            Same as <methodname>setCommentFeedLink()</methodname> except it
                            accepts an array of arrays, where each subarray contains the
                            expected parameters of <methodname>setCommentFeedLink()</methodname>.
                        </entry>
                    </row>
                    
                    <row>
                        <entry><methodname>setEncoding()</methodname></entry>

                        <entry>
                            Sets the encoding of entry text. This will default to UTF-8 which
                            is the preferred encoding.
                        </entry>
                    </row>
                </tbody>
            </tgroup>
        </table>
        
        <note>
            <para>In addition to these setters, there are also matching getters to retrieve data from the
            Entry data container.</para>
        </note>
    </sect2>
</sect1>