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

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="zend.feed.consuming-rss">
   4     <title>Consuming an RSS Feed</title>
   5
   6     <para>
   7         Reading an <acronym>RSS</acronym> feed is as simple as instantiating a
   8         <classname>Zend_Feed_Rss</classname> object with the <acronym>URL</acronym> of the feed:
   9     </para>
  10
  11     <programlisting language="php"><![CDATA[
  12 $channel = new Zend_Feed_Rss('http://rss.example.com/channelName');
  13 ]]></programlisting>
  14
  15     <para>
  16         If any errors occur fetching the feed, a <classname>Zend_Feed_Exception</classname> will be
  17         thrown.
  18     </para>
  19
  20     <para>
  21         Once you have a feed object, you can access any of the standard <acronym>RSS</acronym>
  22         "channel" properties directly on the object:
  23     </para>
  24
  25     <programlisting language="php"><![CDATA[
  26 echo $channel->title();
  27 ]]></programlisting>
  28
  29     <para>
  30         Note the function syntax. <classname>Zend_Feed</classname> uses a convention of treating
  31         properties as <acronym>XML</acronym> object if they are requested with variable "getter"
  32         syntax (<command>$obj->property</command>) and as strings if they are access with method
  33         syntax (<command>$obj->property()</command>). This enables access to the full text of any
  34         individual node while still allowing full access to all children.
  35     </para>
  36
  37     <para>
  38         If channel properties have attributes, they are accessible using <acronym>PHP</acronym>'s
  39         array syntax:
  40     </para>
  41
  42     <programlisting language="php"><![CDATA[
  43 echo $channel->category['domain'];
  44 ]]></programlisting>
  45
  46     <para>
  47         Since <acronym>XML</acronym> attributes cannot have children, method syntax is not necessary
  48         for accessing attribute values.
  49     </para>
  50
  51     <para>
  52         Most commonly you'll want to loop through the feed and do something with its entries.
  53         <classname>Zend_Feed_Abstract</classname> implements <acronym>PHP</acronym>'s
  54         <classname>Iterator</classname> interface, so printing all titles of articles in a channel
  55         is just a matter of:
  56     </para>
  57
  58     <programlisting language="php"><![CDATA[
  59 foreach ($channel as $item) {
  60     echo $item->title() . "\n";
  61 }
  62 ]]></programlisting>
  63
  64     <para>
  65         If you are not familiar with <acronym>RSS</acronym>, here are the standard elements you can
  66         expect to be available in an <acronym>RSS</acronym> channel and in individual
  67         <acronym>RSS</acronym> items (entries).
  68     </para>
  69
  70     <para>
  71         Required channel elements:
  72     </para>
  73
  74     <itemizedlist>
  75         <listitem>
  76             <para><property>title</property> - The name of the channel</para>
  77         </listitem>
  78
  79         <listitem>
  80             <para>
  81                 <property>link</property> - The <acronym>URL</acronym> of the web site
  82                 corresponding to the channel
  83             </para>
  84         </listitem>
  85
  86         <listitem>
  87             <para>
  88                 <property>description</property> - A sentence or several describing the channel
  89             </para>
  90         </listitem>
  91     </itemizedlist>
  92
  93     <para>
  94         Common optional channel elements:
  95     </para>
  96
  97     <itemizedlist>
  98         <listitem>
  99             <para>
 100                 <property>pubDate</property> - The publication date of this set of content, in
 101                 <acronym>RFC</acronym> 822 date format
 102             </para>
 103         </listitem>
 104
 105         <listitem>
 106             <para><property>language</property> - The language the channel is written in</para>
 107         </listitem>
 108
 109         <listitem>
 110             <para>
 111                 <property>category</property> - One or more (specified by multiple tags)
 112                 categories the channel belongs to
 113             </para>
 114         </listitem>
 115     </itemizedlist>
 116
 117     <para>
 118         <acronym>RSS</acronym> <emphasis>&lt;item&gt;</emphasis> elements do not have any strictly
 119         required elements. However, either <property>title</property> or
 120         <property>description</property> must be present.
 121     </para>
 122
 123     <para>
 124         Common item elements:
 125     </para>
 126
 127     <itemizedlist>
 128         <listitem>
 129             <para><property>title</property> - The title of the item</para>
 130         </listitem>
 131
 132         <listitem>
 133             <para><property>link</property> - The <acronym>URL</acronym> of the item</para>
 134         </listitem>
 135
 136         <listitem>
 137             <para><property>description</property> - A synopsis of the item</para>
 138         </listitem>
 139
 140         <listitem>
 141             <para><property>author</property> - The author's email address</para>
 142         </listitem>
 143
 144         <listitem>
 145             <para>
 146                 <property>category</property> - One more categories that the item belongs to
 147             </para>
 148         </listitem>
 149
 150         <listitem>
 151             <para>
 152                 <property>comments</property> - <acronym>URL</acronym> of comments relating to
 153                 this item
 154             </para>
 155         </listitem>
 156
 157         <listitem>
 158             <para>
 159                 <property>pubDate</property> - The date the item was published, in
 160                 <acronym>RFC</acronym> 822 date format
 161             </para>
 162         </listitem>
 163     </itemizedlist>
 164
 165     <para>
 166         In your code you can always test to see if an element is non-empty with:
 167     </para>
 168
 169     <programlisting language="php"><![CDATA[
 170 if ($item->propname()) {
 171     // ... proceed.
 172 }
 173 ]]></programlisting>
 174
 175     <para>
 176         If you use <command>$item->propname</command> instead, you will always get an empty object
 177         which will evaluate to <constant>TRUE</constant>, so your check will fail.
 178     </para>
 179
 180     <para>
 181         For further information, the official <acronym>RSS</acronym> 2.0 specification is available
 182         at: <ulink
 183             url="http://blogs.law.harvard.edu/tech/rss">http://blogs.law.harvard.edu/tech/rss</ulink>
 184     </para>
 185 </sect1>
 186 <!--
 187 vim:se ts=4 sw=4 et:
 188 -->