repo_zf1/documentation/manual/en/module_specs/Zend_Feed-ConsumingRss.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect1 id="zend.feed.consuming-rss">
    <title>Consuming an RSS Feed</title>
    <para>
        Reading an <acronym>RSS</acronym> feed is as simple as instantiating a
        <classname>Zend_Feed_Rss</classname> object with the <acronym>URL</acronym> of the feed:
    </para>
    <programlisting language="php"><![CDATA[
$channel = new Zend_Feed_Rss('http://rss.example.com/channelName');
]]></programlisting>
    <para>
        If any errors occur fetching the feed, a <classname>Zend_Feed_Exception</classname> will be
        thrown.
    </para>

    <para>
        Once you have a feed object, you can access any of the standard <acronym>RSS</acronym>
        "channel" properties directly on the object:
    </para>
    <programlisting language="php"><![CDATA[
echo $channel->title();
]]></programlisting>
    <para>
        Note the function syntax. <classname>Zend_Feed</classname> uses a convention of treating
        properties as <acronym>XML</acronym> object if they are requested with variable "getter"
        syntax (<code>$obj->property</code>) and as strings if they are access with method syntax
        (<code>$obj->property()</code>). This enables access to the full text of any individual node
        while still allowing full access to all children.
    </para>

    <para>
        If channel properties have attributes, they are accessible using <acronym>PHP</acronym>'s
        array syntax:
    </para>
    <programlisting language="php"><![CDATA[
echo $channel->category['domain'];
]]></programlisting>
    <para>
        Since <acronym>XML</acronym> attributes cannot have children, method syntax is not necessary
        for accessing attribute values.
    </para>

    <para>
        Most commonly you'll want to loop through the feed and do something with its entries.
        <classname>Zend_Feed_Abstract</classname> implements <acronym>PHP</acronym>'s
        <code>Iterator</code> interface, so printing all titles of articles in a channel is just a
        matter of:
    </para>
    <programlisting language="php"><![CDATA[
foreach ($channel as $item) {
    echo $item->title() . "\n";
}
]]></programlisting>
    <para>
        If you are not familiar with <acronym>RSS</acronym>, here are the standard elements you can
        expect to be available in an <acronym>RSS</acronym> channel and in individual
        <acronym>RSS</acronym> items (entries).
    </para>

    <para>
        Required channel elements:
    </para>

    <para>
        <itemizedlist>
            <listitem>
                <para><code>title</code> - The name of the channel</para>
            </listitem>
            <listitem>
                <para>
                    <code>link</code> - The <acronym>URL</acronym> of the web site corresponding to
                    the channel
                </para>
            </listitem>
            <listitem>
                <para><code>description</code> - A sentence or several describing the channel</para>
            </listitem>
        </itemizedlist>
    </para>

    <para>
        Common optional channel elements:
    </para>

    <para>
        <itemizedlist>
            <listitem>
                <para>
                    <code>pubDate</code> - The publication date of this set of content, in
                    <acronym>RFC</acronym> 822 date format
                </para>
            </listitem>
            <listitem>
                <para><code>language</code> - The language the channel is written in</para>
            </listitem>
            <listitem>
                <para>
                    <code>category</code> - One or more (specified by multiple tags) categories the
                    channel belongs to
                </para>
            </listitem>
        </itemizedlist>
    </para>

    <para>
        <acronym>RSS</acronym> <code>&lt;item&gt;</code> elements do not have any strictly required
        elements. However, either <code>title</code> or <code>description</code> must be present.
    </para>

    <para>
        Common item elements:
    </para>

    <para>
        <itemizedlist>
            <listitem>
                <para><code>title</code> - The title of the item</para>
            </listitem>
            <listitem>
                <para><code>link</code> - The <acronym>URL</acronym> of the item</para>
            </listitem>
            <listitem>
                <para><code>description</code> - A synopsis of the item</para>
            </listitem>
            <listitem>
                <para><code>author</code> - The author's email address</para>
            </listitem>
            <listitem>
                <para>
                    <code>category</code> - One more categories that the item belongs to
                </para>
            </listitem>
            <listitem>
                <para>
                    <code>comments</code> - <acronym>URL</acronym> of comments relating to this item
                </para>
            </listitem>
            <listitem>
                <para>
                    <code>pubDate</code> - The date the item was published, in
                    <acronym>RFC</acronym> 822 date format
                </para>
            </listitem>
        </itemizedlist>
    </para>

    <para>
        In your code you can always test to see if an element is non-empty with:
    </para>
    <programlisting language="php"><![CDATA[
if ($item->propname()) {
    // ... proceed.
}
]]></programlisting>

    <para>
        If you use <code>$item->propname</code> instead, you will always get an empty object which
        will evaluate to <constant>TRUE</constant>, so your check will fail.
    </para>

    <para>
        For further information, the official <acronym>RSS</acronym> 2.0 specification is available
        at: <ulink
            url="http://blogs.law.harvard.edu/tech/rss">http://blogs.law.harvard.edu/tech/rss</ulink>
    </para>
</sect1>
<!--
vim:se ts=4 sw=4 et:
-->