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 (<command>$obj->property</command>) and as strings if they are access with method
        syntax (<command>$obj->property()</command>). 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
        <classname>Iterator</classname> 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>

    <itemizedlist>
        <listitem>
            <para><property>title</property> - The name of the channel</para>
        </listitem>

        <listitem>
            <para>
                <property>link</property> - The <acronym>URL</acronym> of the web site
                corresponding to the channel
            </para>
        </listitem>

        <listitem>
            <para>
                <property>description</property> - A sentence or several describing the channel
            </para>
        </listitem>
    </itemizedlist>

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

    <itemizedlist>
        <listitem>
            <para>
                <property>pubDate</property> - The publication date of this set of content, in
                <acronym>RFC</acronym> 822 date format
            </para>
        </listitem>

        <listitem>
            <para><property>language</property> - The language the channel is written in</para>
        </listitem>

        <listitem>
            <para>
                <property>category</property> - One or more (specified by multiple tags)
                categories the channel belongs to
            </para>
        </listitem>
    </itemizedlist>

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

    <para>
        Common item elements:
    </para>

    <itemizedlist>
        <listitem>
            <para><property>title</property> - The title of the item</para>
        </listitem>

        <listitem>
            <para><property>link</property> - The <acronym>URL</acronym> of the item</para>
        </listitem>

        <listitem>
            <para><property>description</property> - A synopsis of the item</para>
        </listitem>

        <listitem>
            <para><property>author</property> - The author's email address</para>
        </listitem>

        <listitem>
            <para>
                <property>category</property> - One more categories that the item belongs to
            </para>
        </listitem>

        <listitem>
            <para>
                <property>comments</property> - <acronym>URL</acronym> of comments relating to
                this item
            </para>
        </listitem>

        <listitem>
            <para>
                <property>pubDate</property> - The date the item was published, in
                <acronym>RFC</acronym> 822 date format
            </para>
        </listitem>
    </itemizedlist>

    <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 <command>$item->propname</command> 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:
-->