documentation/manual/en/module_specs/Zend_Feed_Reader.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="zend.feed.reader">
   4     <title>Zend_Feed_Reader</title>
   5
   6     <sect2 id="zend.feed.reader.introduction">
   7         <title>Introduction</title>
   8
   9         <para>
  10             <classname>Zend_Feed_Reader</classname> is a component used to
  11             consume <acronym>RSS</acronym> and Atom feeds of any version, including
  12             <acronym>RDF</acronym>/<acronym>RSS</acronym> 1.0,
  13             <acronym>RSS</acronym> 2.0 and Atom 0.3/1.0. The <acronym>API</acronym> for
  14             retrieving feed data is
  15             deliberately simple since <classname>Zend_Feed_Reader</classname> is
  16             capable of searching any feed of any type for the information
  17             requested through the <acronym>API</acronym>. If the typical elements containing this
  18             information are not present, it will adapt and fall back on a
  19             variety of alternative elements instead. This ability to choose from
  20             alternatives removes the need for users to create their own
  21             abstraction layer on top of the component to make it useful or have
  22             any in-depth knowledge of the underlying standards, current
  23             alternatives, and namespaced extensions.
  24         </para>
  25
  26         <para>
  27             Internally, <classname>Zend_Feed_Reader</classname> works almost
  28             entirely on the basis of making XPath queries against the feed <acronym>XML</acronym>'s
  29             Document Object Model. The <acronym>DOM</acronym> is not exposed though a chained
  30             property <acronym>API</acronym> like <classname>Zend_Feed</classname> though the
  31             underlying <classname>DOMDocument</classname>,
  32             <classname>DOMElement</classname> and
  33             <classname>DOMXPath</classname> objects are exposed for external
  34             manipulation. This singular approach to parsing is consistent and
  35             the component offers a plugin system to add to the Feed and Entry
  36             level <acronym>API</acronym> by writing Extensions on a similar basis.
  37         </para>
  38
  39         <para>
  40             Performance is assisted in three ways. First of all,
  41             <classname>Zend_Feed_Reader</classname> supports caching using
  42             <classname>Zend_Cache</classname> to maintain a copy of the original
  43             feed <acronym>XML</acronym>. This allows you to skip network requests for a feed
  44             <acronym>URI</acronym> if
  45             the cache is valid. Second, the Feed and Entry level <acronym>API</acronym> is backed
  46             by an internal cache (non-persistant) so repeat <acronym>API</acronym> calls for the
  47             same feed will avoid additional <acronym>DOM</acronym>/XPath use. Thirdly, importing
  48             feeds from a <acronym>URI</acronym> can take advantage of
  49             <acronym>HTTP</acronym> Conditional GET requests
  50             which allow servers to issue an empty 304 response when the
  51             requested feed has not changed since the last time you requested it.
  52             In the final case, an instance of <classname>Zend_Cache</classname>
  53             will hold the last received feed along with the ETag and
  54             Last-Modified header values sent in the <acronym>HTTP</acronym> response.
  55         </para>
  56
  57         <para>
  58             In relation to <classname>Zend_Feed</classname>,
  59             <classname>Zend_Feed_Reader</classname> was formulated as a free
  60             standing replacement for <classname>Zend_Feed</classname> but it is
  61             not backwards compatible with <classname>Zend_Feed</classname>.
  62             Rather it is an alternative following a different ideology focused
  63             on being simple to use, flexible, consistent and extendable through
  64             the plugin system. <classname>Zend_Feed_Reader</classname> is also
  65             not capable of constructing feeds and delegates this responsibility
  66             to <classname>Zend_Feed_Writer</classname>, its sibling in arms.
  67         </para>
  68     </sect2>
  69
  70     <sect2 id="zend.feed.reader.import">
  71         <title>Importing Feeds</title>
  72
  73         <para>
  74             Importing a feed with <classname>Zend_Feed_Reader</classname> is not
  75             that much different to <classname>Zend_Feed</classname>. Feeds can
  76             be imported from a string, file, <acronym>URI</acronym> or an instance of type
  77             <classname>Zend_Feed_Abstract</classname>. Importing from a <acronym>URI</acronym> can
  78             additionally utilise a <acronym>HTTP</acronym> Conditional GET request. If importing
  79             fails, an exception will be raised. The end result will be an object
  80             of type <classname>Zend_Feed_Reader_FeedInterface</classname>, the
  81             core implementations of which are
  82             <classname>Zend_Feed_Reader_Feed_Rss</classname> and
  83             <classname>Zend_Feed_Reader_Feed_Atom</classname>
  84             (<classname>Zend_Feed</classname> took all the short names!). Both
  85             objects support multiple (all existing) versions of these broad feed
  86             types.
  87         </para>
  88
  89         <para>
  90             In the following example, we import an <acronym>RDF</acronym>/<acronym>RSS</acronym> 1.0
  91             feed and extract some basic information that can be saved to a database or
  92             elsewhere.
  93         </para>
  94
  95         <programlisting language="php"><![CDATA[
  96 $feed = Zend_Feed_Reader::import('http://www.planet-php.net/rdf/');
  97 $data = array(
  98     'title'        => $feed->getTitle(),
  99     'link'         => $feed->getLink(),
 100     'dateModified' => $feed->getDateModified(),
 101     'description'  => $feed->getDescription(),
 102     'language'     => $feed->getLanguage(),
 103     'entries'      => array(),
 104 );
 105
 106 foreach ($feed as $entry) {
 107     $edata = array(
 108         'title'        => $entry->getTitle(),
 109         'description'  => $entry->getDescription(),
 110         'dateModified' => $entry->getDateModified(),
 111         'authors'       => $entry->getAuthors(),
 112         'link'         => $entry->getLink(),
 113         'content'      => $entry->getContent()
 114     );
 115     $data['entries'][] = $edata;
 116 }
 117 ]]></programlisting>
 118
 119         <para>
 120             The example above demonstrates
 121             <classname>Zend_Feed_Reader</classname>'s <acronym>API</acronym>, and it also
 122             demonstrates some of its internal operation. In reality, the <acronym>RDF</acronym>
 123             feed selected does not have any native date or author elements,
 124             however it does utilise the Dublin Core 1.1 module which offers
 125             namespaced creator and date elements.
 126             <classname>Zend_Feed_Reader</classname> falls back on these and
 127             similar options if no relevant native elements exist. If it
 128             absolutely cannot find an alternative it will return <constant>NULL</constant>,
 129             indicating the information could not be found in the feed. You
 130             should note that classes implementing
 131             <classname>Zend_Feed_Reader_FeedInterface</classname> also implement
 132             the <acronym>SPL</acronym> <classname>Iterator</classname> and
 133             <classname>Countable</classname> interfaces.
 134         </para>
 135
 136         <para>
 137             Feeds can also be imported from strings, files, and even objects of
 138             type <classname>Zend_Feed_Abstract</classname>.
 139         </para>
 140
 141         <programlisting language="php"><![CDATA[
 142 // from a URI
 143 $feed = Zend_Feed_Reader::import('http://www.planet-php.net/rdf/');
 144
 145 // from a String
 146 $feed = Zend_Feed_Reader::importString($feedXmlString);
 147
 148 // from a file
 149 $feed = Zend_Feed_Reader::importFile('./feed.xml');
 150
 151 // from a Zend_Feed_Abstract object
 152 $zfeed = Zend_Feed::import('http://www.planet-php.net/atom/');
 153 $feed  = Zend_Feed_Reader::importFeed($zfeed);
 154 ]]></programlisting>
 155     </sect2>
 156
 157     <sect2 id="zend.feed.reader.sources">
 158         <title>Retrieving Underlying Feed and Entry Sources</title>
 159
 160         <para>
 161             <classname>Zend_Feed_Reader</classname> does its best not to stick
 162             you in a narrow confine. If you need to work on a feed outside of
 163             <classname>Zend_Feed_Reader</classname>, you can extract the base
 164             <classname>DOMDocument</classname> or
 165             <classname>DOMElement</classname> objects from any class, or even an
 166             <acronym>XML</acronym> string containing these. Also provided are methods to extract
 167             the current <classname>DOMXPath</classname> object (with all core
 168             and Extension namespaces registered) and the correct prefix used in
 169             all XPath queries for the current Feed or Entry. The basic methods
 170             to use (on any object) are <methodname>saveXml()</methodname>,
 171             <methodname>getDomDocument()</methodname>,
 172             <methodname>getElement()</methodname>,
 173             <methodname>getXpath()</methodname> and
 174             <methodname>getXpathPrefix()</methodname>. These will let you break
 175             free of <classname>Zend_Feed_Reader</classname> and do whatever else
 176             you want.
 177         </para>
 178
 179         <itemizedlist>
 180             <listitem>
 181                 <para>
 182                     <methodname>saveXml()</methodname> returns an <acronym>XML</acronym> string
 183                     containing only the element representing the current object.
 184                 </para>
 185             </listitem>
 186
 187             <listitem>
 188                 <para>
 189                     <methodname>getDomDocument()</methodname> returns the
 190                     <classname>DOMDocument</classname> object representing the
 191                     entire feed (even if called from an Entry object).
 192                 </para>
 193             </listitem>
 194
 195             <listitem>
 196                 <para>
 197                     <methodname>getElement()</methodname> returns the
 198                     <classname>DOMElement</classname> of the current object
 199                     (i.e. the Feed or current Entry).
 200                 </para>
 201             </listitem>
 202
 203             <listitem>
 204                 <para>
 205                     <methodname>getXpath()</methodname> returns the
 206                     <classname>DOMXPath</classname> object for the current feed
 207                     (even if called from an Entry object) with the namespaces of
 208                     the current feed type and all loaded Extensions
 209                     pre-registered.
 210                 </para>
 211             </listitem>
 212
 213             <listitem>
 214                 <para>
 215                     <methodname>getXpathPrefix()</methodname> returns the query
 216                     prefix for the current object (i.e. the Feed or current
 217                     Entry) which includes the correct XPath query path for that
 218                     specific Feed or Entry.
 219                 </para>
 220             </listitem>
 221         </itemizedlist>
 222
 223         <para>
 224             Here's an example where a feed might include an <acronym>RSS</acronym> Extension not
 225             supported by <classname>Zend_Feed_Reader</classname> out of the box.
 226             Notably, you could write and register an Extension (covered later)
 227             to do this, but that's not always warranted for a quick check. You
 228             must register any new namespaces on the
 229             <classname>DOMXPath</classname> object before use unless they are
 230             registered by <classname>Zend_Feed_Reader</classname> or an
 231             Extension beforehand.
 232         </para>
 233
 234         <programlisting language="php"><![CDATA[
 235 $feed        = Zend_Feed_Reader::import('http://www.planet-php.net/rdf/');
 236 $xpathPrefix = $feed->getXpathPrefix();
 237 $xpath       = $feed->getXpath();
 238 $xpath->registerNamespace('admin', 'http://webns.net/mvcb/');
 239 $reportErrorsTo = $xpath->evaluate('string('
 240                                  . $xpathPrefix
 241                                  . '/admin:errorReportsTo)');
 242 ]]></programlisting>
 243
 244         <warning>
 245             <para>
 246                 If you register an already registered namespace with a different
 247                 prefix name to that used internally by
 248                 <classname>Zend_Feed_Reader</classname>, it will break the
 249                 internal operation of this component.
 250             </para>
 251         </warning>
 252     </sect2>
 253
 254     <sect2 id="zend.feed.reader.cache-request">
 255         <title>Cache Support and Intelligent Requests</title>
 256
 257         <sect3 id="zend.feed.reader.cache-request.cache">
 258             <title>Adding Cache Support to Zend_Feed_Reader</title>
 259
 260             <para>
 261                 <classname>Zend_Feed_Reader</classname> supports using an
 262                 instance of <classname>Zend_Cache</classname> to cache feeds (as
 263                 <acronym>XML</acronym>) to avoid unnecessary network requests. Adding a cache is as
 264                 simple here as it is for other Zend Framework components, create
 265                 and configure your cache and then tell
 266                 <classname>Zend_Feed_Reader</classname> to use it! The cache key
 267                 used is "<classname>Zend_Feed_Reader_</classname>" followed by the
 268                 <acronym>MD5</acronym> hash of the feed's <acronym>URI</acronym>.
 269             </para>
 270
 271             <programlisting language="php"><![CDATA[
 272 $frontendOptions = array(
 273    'lifetime' => 7200,
 274    'automatic_serialization' => true
 275 );
 276 $backendOptions = array('cache_dir' => './tmp/');
 277 $cache = Zend_Cache::factory(
 278     'Core', 'File', $frontendOptions, $backendOptions
 279 );
 280
 281 Zend_Feed_Reader::setCache($cache);
 282 ]]></programlisting>
 283
 284             <note>
 285                 <para>
 286                     While it's a little off track, you should also consider
 287                     adding a cache to
 288                     <classname>Zend_Loader_PluginLoader</classname> which is
 289                     used by <classname>Zend_Feed_Reader</classname> to load
 290                     Extensions.
 291                 </para>
 292             </note>
 293         </sect3>
 294
 295         <sect3 id="zend.feed.reader.cache-request.http-conditional-get">
 296             <title>HTTP Conditional GET Support</title>
 297
 298             <para>
 299                 The big question often asked when importing a feed frequently, is
 300                 if it has even changed. With a cache enabled, you can add <acronym>HTTP</acronym>
 301                 Conditional GET support to your arsenal to answer that question.
 302             </para>
 303
 304             <para>
 305                 Using this method, you can request feeds from <acronym>URI</acronym>s and include
 306                 their last known ETag and Last-Modified response header values
 307                 with the request (using the If-None-Match and If-Modified-Since
 308                 headers). If the feed on the server remains unchanged, you
 309                 should receive a 304 response which tells
 310                 <classname>Zend_Feed_Reader</classname> to use the cached
 311                 version. If a full feed is sent in a response with a status code
 312                 of 200, this means the feed has changed and
 313                 <classname>Zend_Feed_Reader</classname> will parse the new
 314                 version and save it to the cache. It will also cache the new
 315                 ETag and Last-Modified header values for future use.
 316             </para>
 317
 318             <para>
 319                 These "conditional" requests are not guaranteed to be supported
 320                 by the server you request a <acronym>URI</acronym> of, but can be attempted
 321                 regardless. Most common feed sources like blogs should however
 322                 have this supported. To enable conditional requests, you will
 323                 need to provide a cache to <classname>Zend_Feed_Reader</classname>.
 324             </para>
 325
 326             <programlisting language="php"><![CDATA[
 327 $frontendOptions = array(
 328    'lifetime' => 86400,
 329    'automatic_serialization' => true
 330 );
 331 $backendOptions = array('cache_dir' => './tmp/');
 332 $cache = Zend_Cache::factory(
 333     'Core', 'File', $frontendOptions, $backendOptions
 334 );
 335
 336 Zend_Feed_Reader::setCache($cache);
 337 Zend_Feed_Reader::useHttpConditionalGet();
 338
 339 $feed = Zend_Feed_Reader::import('http://www.planet-php.net/rdf/');
 340 ]]></programlisting>
 341
 342             <para>
 343                 In the example above, with <acronym>HTTP</acronym> Conditional GET requests enabled,
 344                 the response header values for ETag and Last-Modified will be cached
 345                 along with the feed. For the next 24hrs (the cache lifetime), feeds will
 346                 only be updated on the cache if a non-304 response is received
 347                 containing a valid <acronym>RSS</acronym> or Atom <acronym>XML</acronym> document.
 348             </para>
 349
 350             <para>
 351                 If you intend on managing request headers from outside
 352                 <classname>Zend_Feed_Reader</classname>, you can set the
 353                 relevant If-None-Matches and If-Modified-Since request headers
 354                 via the <acronym>URI</acronym> import method.
 355             </para>
 356
 357             <programlisting language="php"><![CDATA[
 358 $lastEtagReceived = '5e6cefe7df5a7e95c8b1ba1a2ccaff3d';
 359 $lastModifiedDateReceived = 'Wed, 08 Jul 2009 13:37:22 GMT';
 360 $feed = Zend_Feed_Reader::import(
 361     $uri, $lastEtagReceived, $lastModifiedDateReceived
 362 );
 363 ]]></programlisting>
 364         </sect3>
 365     </sect2>
 366
 367     <sect2 id="zend.feed.reader.locate">
 368         <title>Locating Feed URIs from Websites</title>
 369
 370         <para>
 371             These days, many websites are aware that the location of their <acronym>XML</acronym>
 372             feeds is not always obvious. A small <acronym>RDF</acronym>, <acronym>RSS</acronym> or
 373             Atom graphic helps when the user is reading the page, but what about when a machine
 374             visits trying to identify where your feeds are located? To assist in
 375             this, websites may point to their feeds using &lt;link&gt; tags in
 376             the &lt;head&gt; section of their <acronym>HTML</acronym>. To take advantage of this,
 377             you can use <classname>Zend_Feed_Reader</classname> to locate these
 378             feeds using the static <methodname>findFeedLinks()</methodname>
 379             method.
 380         </para>
 381
 382         <para>
 383             This method calls any <acronym>URI</acronym> and searches for the location of
 384             <acronym>RSS</acronym>, <acronym>RDF</acronym>
 385             and Atom feeds assuming the website's <acronym>HTML</acronym> contains the relevant
 386             links. It then returns a value object where you can check for the existence of a
 387             <acronym>RSS</acronym>, <acronym>RDF</acronym> or Atom feed <acronym>URI</acronym>.
 388         </para>
 389
 390         <para>
 391             The returned object is an <classname>ArrayObject</classname> subclass
 392             called <classname>Zend_Feed_Reader_Collection_FeedLink</classname> so you can cast
 393             it to an array, or iterate over it, to access all the detected links.
 394             However, as a simple shortcut, you can just grab the first RSS, RDF
 395             or Atom link using its public properties as in the example below. Otherwise,
 396             each element of the <classname>ArrayObject</classname> is a simple array
 397             with the keys "type" and "uri" where the type is one of "rdf", "rss" or
 398             "atom".
 399         </para>
 400
 401         <programlisting language="php"><![CDATA[
 402 $links = Zend_Feed_Reader::findFeedLinks('http://www.planet-php.net');
 403
 404 if(isset($links->rdf)) {
 405     echo $links->rdf, "\n"; // http://www.planet-php.org/rdf/
 406 }
 407 if(isset($links->rss)) {
 408     echo $links->rss, "\n"; // http://www.planet-php.org/rss/
 409 }
 410 if(isset($links->atom)) {
 411     echo $links->atom, "\n"; // http://www.planet-php.org/atom/
 412 }
 413 ]]></programlisting>
 414
 415         <para>
 416             Based on these links, you can then import from whichever source you
 417             wish in the usual manner.
 418         </para>
 419
 420         <para>
 421             This quick method only gives you one link for each feed type, but
 422             websites may indicate many links of any type. Perhaps it's a news
 423             site with a RSS feed for each news category. You can iterate over
 424             all links using the ArrayObject's iterator.
 425         </para>
 426
 427         <programlisting language="php"><![CDATA[
 428 $links = Zend_Feed_Reader::findFeedLinks('http://www.planet-php.net');
 429
 430 foreach ($links as $link) {
 431     echo $link['uri'], "\n";
 432 }
 433 ]]></programlisting>
 434   </sect2>
 435
 436   <sect2 id="zend.feed.reader.attribute-collections">
 437         <title>Attribute Collections</title>
 438
 439         <para>
 440             In an attempt to simplify return types, with Zend Framework 1.10 return
 441             types from the various feed and entry level methods may include an object
 442             of type <classname>Zend_Feed_Reader_Collection_CollectionAbstract</classname>.
 443             Despite the special class name which I'll explain below, this is just a simple
 444             subclass of SPL's <classname>ArrayObject</classname>.
 445         </para>
 446
 447         <para>
 448             The main purpose here is to allow the presentation of as much data as possible
 449             from the requested elements, while still allowing access to the most relevant
 450             data as a simple array. This also enforces a standard approach to returning
 451             such data which previously may have wandered between arrays and objects.
 452         </para>
 453
 454         <para>
 455             The new class type acts identically to <classname>ArrayObject</classname>
 456             with the sole addition being a new method <methodname>getValues()</methodname>
 457             which returns a simple flat array containing the most relevant information.
 458         </para>
 459
 460         <para>
 461             A simple example of this is
 462             <methodname>Zend_Feed_Reader_FeedInterface::getCategories()</methodname>. When used with
 463             any RSS or Atom feed, this method will return category data as a container object called
 464             <classname>Zend_Feed_Reader_Collection_Category</classname>. The container object will
 465             contain, per category, three fields of data: term, scheme and label. The "term" is the
 466             basic category name, often machine readable (i.e. plays nice with URIs). The scheme
 467             represents a categorisation scheme (usually a URI identifier) also known as a "domain"
 468             in RSS 2.0. The "label" is a human readable category name which supports
 469             <acronym>HTML</acronym> entities. In RSS 2.0, there is no label attribute so it is
 470             always set to the same value as the term for convenience.
 471         </para>
 472
 473         <para>
 474             To access category labels by themselves in a simple value array,
 475             you might commit to something like:
 476         </para>
 477
 478         <programlisting language="php"><![CDATA[
 479 $feed = Zend_Feed_Reader::import('http://www.example.com/atom.xml');
 480 $categories = $feed->getCategories();
 481 $labels = array();
 482 foreach ($categories as $cat) {
 483     $labels[] = $cat['label']
 484 }
 485 ]]></programlisting>
 486
 487         <para>
 488             It's a contrived example, but the point is that the labels are tied up with
 489             other information.
 490         </para>
 491
 492         <para>
 493             However, the container class allows you to access the "most relevant" data
 494             as a simple array using the <methodname>getValues()</methodname> method. The concept
 495             of "most relevant" is obviously a judgement call. For categories it means the category
 496             labels (not the terms or schemes) while for authors it would be the authors' names
 497             (not their email addresses or URIs). The simple array is flat (just values) and passed
 498             through <methodname>array_unique()</methodname> to remove duplication.
 499         </para>
 500
 501         <programlisting language="php"><![CDATA[
 502 $feed = Zend_Feed_Reader::import('http://www.example.com/atom.xml');
 503 $categories = $feed->getCategories();
 504 $labels = $categories->getValues();
 505 ]]></programlisting>
 506
 507         <para>
 508             The above example shows how to extract only labels and nothing else thus
 509             giving simple access to the category labels without any additional work to extract
 510             that data by itself.
 511         </para>
 512   </sect2>
 513
 514   <sect2 id="zend.feed.reader.retrieve-info">
 515         <title>Retrieving Feed Information</title>
 516
 517         <para>
 518             Retrieving information from a feed (we'll cover entries/items in the
 519             next section though they follow identical principals) uses a clearly
 520             defined <acronym>API</acronym> which is exactly the same regardless of whether the feed
 521             in question is <acronym>RSS</acronym>/<acronym>RDF</acronym>/Atom. The same goes for
 522             sub-versions of these standards and we've tested every single
 523             <acronym>RSS</acronym> and Atom version. While
 524             the underlying feed <acronym>XML</acronym> can differ substantially in terms of the
 525             tags and elements they present, they nonetheless are all trying to
 526             convey similar information and to reflect this all the differences
 527             and wrangling over alternative tags are handled internally by
 528             <classname>Zend_Feed_Reader</classname> presenting you with an
 529             identical interface for each. Ideally, you should not have to care
 530             whether a feed is <acronym>RSS</acronym> or Atom so long as you can extract the
 531             information you want.
 532         </para>
 533
 534         <note>
 535             <para>
 536                 While determining common ground between feed types is itself complex, it
 537                 should be noted that RSS in particular is a constantly disputed "specification".
 538                 This has its roots in the original RSS 2.0 document which contains ambiguities
 539                 and does not detail the correct treatment of all elements. As a result, this
 540                 component rigorously applies the RSS 2.0.11 Specification published by the
 541                 RSS Advisory Board and its accompanying RSS Best Practices Profile. No
 542                 other interpretation of RSS 2.0 will be supported though exceptions may
 543                 be allowed where it does not directly prevent the application of the two
 544                 documents mentioned above.
 545             </para>
 546         </note>
 547
 548         <para>
 549             Of course, we don't live in an ideal world so there may be times the
 550             <acronym>API</acronym> just does not cover what you're looking for. To assist you,
 551             <classname>Zend_Feed_Reader</classname> offers a plugin system which
 552             allows you to write Extensions to expand the core <acronym>API</acronym> and cover any
 553             additional data you are trying to extract from feeds. If writing
 554             another Extension is too much trouble, you can simply grab the
 555             underlying <acronym>DOM</acronym> or XPath objects and do it by hand in your
 556             application. Of course, we really do encourage writing an Extension
 557             simply to make it more portable and reusable, and useful Extensions may be proposed
 558             to the Framework for formal addition.
 559         </para>
 560
 561         <para>
 562             Here's a summary of the Core <acronym>API</acronym> for Feeds. You should note it
 563             comprises not only the basic <acronym>RSS</acronym> and Atom standards, but also
 564             accounts for a number of included Extensions bundled with
 565             <classname>Zend_Feed_Reader</classname>. The naming of these
 566             Extension sourced methods remain fairly generic - all Extension
 567             methods operate at the same level as the Core <acronym>API</acronym> though we do allow
 568             you to retrieve any specific Extension object separately if required.
 569         </para>
 570
 571         <table>
 572             <title>Feed Level API Methods</title>
 573
 574             <tgroup cols="2">
 575                 <tbody>
 576                     <row>
 577                         <entry><methodname>getId()</methodname></entry>
 578                         <entry>Returns a unique ID associated with this feed</entry>
 579                     </row>
 580
 581                     <row>
 582                         <entry><methodname>getTitle()</methodname></entry>
 583                         <entry>Returns the title of the feed</entry>
 584                     </row>
 585
 586                     <row>
 587                         <entry><methodname>getDescription()</methodname></entry>
 588                         <entry>Returns the text description of the feed.</entry>
 589                     </row>
 590
 591                     <row>
 592                         <entry><methodname>getLink()</methodname></entry>
 593
 594                         <entry>
 595                             Returns a <acronym>URI</acronym> to the <acronym>HTML</acronym> website
 596                             containing the same or
 597                             similar information as this feed (i.e. if the feed is from a blog,
 598                             it should provide the blog's <acronym>URI</acronym> where the
 599                             <acronym>HTML</acronym> version of the entries can be read).
 600                         </entry>
 601                     </row>
 602
 603                     <row>
 604                         <entry><methodname>getFeedLink()</methodname></entry>
 605
 606                         <entry>
 607                             Returns the <acronym>URI</acronym> of this feed, which may be the
 608                             same as the <acronym>URI</acronym> used to import the feed. There
 609                             are important cases where the feed link may differ because the source
 610                             URI is being updated and is intended to be removed in the future.
 611                         </entry>
 612                     </row>
 613
 614                     <row>
 615                         <entry><methodname>getAuthors()</methodname></entry>
 616
 617                         <entry>
 618                             Returns an object of type
 619                             <classname>Zend_Feed_Reader_Collection_Author</classname> which is an
 620                             <classname>ArrayObject</classname> whose elements are each simple arrays
 621                             containing any combination of the keys "name", "email" and "uri". Where
 622                             irrelevant to the source data, some of these keys may be omitted.
 623                         </entry>
 624                     </row>
 625
 626                     <row>
 627                         <entry><methodname>getAuthor(integer $index = 0)</methodname></entry>
 628
 629                         <entry>
 630                             Returns either the first author known, or with the
 631                             optional <varname>$index</varname> parameter any specific
 632                             index on the array of Authors as described above (returning
 633                             <constant>NULL</constant> if an invalid index).
 634                         </entry>
 635                     </row>
 636
 637                     <row>
 638                         <entry><methodname>getDateCreated()</methodname></entry>
 639
 640                         <entry>
 641                             Returns the date on which this feed was created. Generally
 642                             only applicable to Atom where it represents the date the resource
 643                             described by an Atom 1.0 document was created. The returned date
 644                             will be a <classname>Zend_Date</classname> object.
 645                         </entry>
 646                     </row>
 647
 648                     <row>
 649                         <entry><methodname>getDateModified()</methodname></entry>
 650
 651                         <entry>
 652                             Returns the date on which this feed was last modified. The returned date
 653                             will be a <classname>Zend_Date</classname> object.
 654                         </entry>
 655                     </row>
 656
 657                     <row>
 658                         <entry><methodname>getLastBuildDate()</methodname></entry>
 659
 660                         <entry>
 661                             Returns the date on which this feed was last built. The returned date
 662                             will be a <classname>Zend_Date</classname> object. This is only
 663                             supported by RSS - Atom feeds will always return NULL.
 664                         </entry>
 665                     </row>
 666
 667                     <row>
 668                         <entry><methodname>getLanguage()</methodname></entry>
 669
 670                         <entry>
 671                             Returns the language of the feed (if defined) or simply the
 672                             language noted in the <acronym>XML</acronym> document.
 673                         </entry>
 674                     </row>
 675
 676                     <row>
 677                         <entry><methodname>getGenerator()</methodname></entry>
 678
 679                         <entry>
 680                             Returns the generator of the feed, e.g. the software which
 681                             generated it. This may differ between <acronym>RSS</acronym> and Atom
 682                             since Atom defines a different notation.
 683                         </entry>
 684                     </row>
 685
 686                     <row>
 687                         <entry><methodname>getCopyright()</methodname></entry>
 688                         <entry>Returns any copyright notice associated with the feed.</entry>
 689                     </row>
 690
 691                     <row>
 692                         <entry><methodname>getHubs()</methodname></entry>
 693
 694                         <entry>
 695                             Returns an array of all Hub Server <acronym>URI</acronym> endpoints
 696                             which are advertised by the feed for use with the Pubsubhubbub
 697                             Protocol, allowing subscriptions to the feed for real-time updates.
 698                         </entry>
 699                     </row>
 700
 701                     <row>
 702                         <entry><methodname>getCategories()</methodname></entry>
 703
 704                         <entry>
 705                             Returns a <classname>Zend_Feed_Reader_Collection_Category</classname>
 706                             object containing the details of any categories associated with the
 707                             overall feed. The supported fields include "term" (the machine readable
 708                             category name), "scheme" (the categorisation scheme/domain for this
 709                             category), and "label" (a <acronym>HTML</acronym> decoded human readable
 710                             category name). Where any of the three fields are absent from the field,
 711                             they are either set to the closest available alternative or, in the case
 712                             of "scheme", set to <constant>NULL</constant>.
 713                         </entry>
 714                     </row>
 715
 716                     <row>
 717                         <entry><methodname>getImage()</methodname></entry>
 718
 719                         <entry>
 720                             Returns an array containing data relating to any feed image or logo,
 721                             or NULL if no image found. The resulting array may contain the following
 722                             keys: uri, link, title, description, height, and width. Atom logos only
 723                             contain a URI so the remaining metadata is drawn from RSS feeds only.
 724                         </entry>
 725                     </row>
 726                 </tbody>
 727             </tgroup>
 728         </table>
 729
 730         <para>
 731             Given the variety of feeds in the wild, some of these methods will
 732             undoubtedly return <constant>NULL</constant> indicating the relevant information
 733             couldn't be located. Where possible, <classname>Zend_Feed_Reader</classname>
 734             will fall back on alternative elements during its search. For
 735             example, searching an <acronym>RSS</acronym> feed for a modification date is more
 736             complicated than it looks. <acronym>RSS</acronym> 2.0 feeds should include a
 737             <command>&lt;lastBuildDate&gt;</command> tag and (or) a
 738             <command>&lt;pubDate&gt;</command> element. But what if it doesn't, maybe
 739             this is an <acronym>RSS</acronym> 1.0 feed? Perhaps it instead has an
 740             <command>&lt;atom:updated&gt;</command> element with identical information
 741             (Atom may be used to supplement <acronym>RSS</acronym>'s syntax)? Failing that, we
 742             could simply look at the entries, pick the most recent, and use its
 743             <command>&lt;pubDate&gt;</command> element. Assuming it exists... Many
 744             feeds also use Dublin Core 1.0/1.1 <command>&lt;dc:date&gt;</command>
 745             elements for feeds and entries. Or we could find Atom lurking again.
 746         </para>
 747
 748         <para>
 749             The point is, <classname>Zend_Feed_Reader</classname> was designed
 750             to know this. When you ask for the modification date (or anything
 751             else), it will run off and search for all these alternatives until
 752             it either gives up and returns <constant>NULL</constant>, or finds an
 753             alternative that should have the right answer.
 754         </para>
 755
 756         <para>
 757             In addition to the above methods, all Feed objects implement methods
 758             for retrieving the <acronym>DOM</acronym> and XPath objects for the current feeds as
 759             described earlier. Feed objects also implement the <acronym>SPL</acronym> Iterator and
 760             Countable interfaces. The extended <acronym>API</acronym> is summarised below.
 761         </para>
 762
 763         <table>
 764             <title>Extended Feed Level API Methods</title>
 765
 766             <tgroup cols="2">
 767                 <tbody>
 768                     <row>
 769                         <entry><methodname>getDomDocument()</methodname></entry>
 770
 771                         <entry>
 772                             Returns the parent
 773                             <classname>DOMDocument</classname> object for the
 774                             entire source <acronym>XML</acronym> document
 775                         </entry>
 776                     </row>
 777
 778                     <row>
 779                         <entry><methodname>getElement()</methodname></entry>
 780
 781                         <entry>
 782                             Returns the current feed level
 783                             <classname>DOMElement</classname> object
 784                         </entry>
 785                     </row>
 786
 787                     <row>
 788                         <entry><methodname>saveXml()</methodname></entry>
 789
 790                         <entry>
 791                             Returns a string containing an <acronym>XML</acronym> document of the
 792                             entire feed element (this is not the original
 793                             document but a rebuilt version)
 794                         </entry>
 795                     </row>
 796
 797                     <row>
 798                         <entry><methodname>getXpath()</methodname></entry>
 799
 800                         <entry>
 801                             Returns the <classname>DOMXPath</classname> object
 802                             used internally to run queries on the
 803                             <classname>DOMDocument</classname> object (this
 804                             includes core and Extension namespaces
 805                             pre-registered)
 806                         </entry>
 807                     </row>
 808
 809                     <row>
 810                         <entry><methodname>getXpathPrefix()</methodname></entry>
 811
 812                         <entry>
 813                             Returns the valid <acronym>DOM</acronym> path prefix prepended
 814                             to all XPath queries matching the feed being queried
 815                         </entry>
 816                     </row>
 817
 818                     <row>
 819                         <entry><methodname>getEncoding()</methodname></entry>
 820
 821                         <entry>
 822                             Returns the encoding of the source <acronym>XML</acronym> document
 823                             (note: this cannot account for errors such as the
 824                             server sending documents in a different encoding). Where not
 825                             defined, the default UTF-8 encoding of Unicode is applied.
 826                         </entry>
 827                     </row>
 828
 829                     <row>
 830                         <entry><methodname>count()</methodname></entry>
 831
 832                         <entry>
 833                             Returns a count of the entries or items this feed contains
 834                             (implements <acronym>SPL</acronym> <classname>Countable</classname>
 835                             interface)
 836                         </entry>
 837                     </row>
 838
 839                     <row>
 840                         <entry><methodname>current()</methodname></entry>
 841
 842                         <entry>
 843                             Returns either the current entry (using the current index
 844                             from <methodname>key()</methodname>)
 845                         </entry>
 846                     </row>
 847
 848                     <row>
 849                         <entry><methodname>key()</methodname></entry>
 850                         <entry>Returns the current entry index</entry>
 851                     </row>
 852
 853                     <row>
 854                         <entry><methodname>next()</methodname></entry>
 855                         <entry>Increments the entry index value by one</entry>
 856                     </row>
 857
 858                     <row>
 859                         <entry><methodname>rewind()</methodname></entry>
 860                         <entry>Resets the entry index to 0</entry>
 861                     </row>
 862
 863                     <row>
 864                         <entry><methodname>valid()</methodname></entry>
 865
 866                         <entry>
 867                             Checks that the current entry index is valid, i.e.
 868                             it does fall below 0 and does not exceed the number
 869                             of entries existing.
 870                         </entry>
 871                     </row>
 872
 873                     <row>
 874                         <entry><methodname>getExtensions()</methodname></entry>
 875
 876                         <entry>
 877                             Returns an array of all Extension objects loaded for
 878                             the current feed (note: both feed-level and entry-level Extensions
 879                             exist, and only feed-level Extensions are returned here).
 880                             The array keys are of the form {ExtensionName}_Feed.
 881                         </entry>
 882                     </row>
 883
 884                     <row>
 885                         <entry><methodname>getExtension(string $name)</methodname></entry>
 886
 887                         <entry>
 888                             Returns an Extension object for the feed registered under the
 889                             provided name. This allows more fine-grained access to
 890                             Extensions which may otherwise be hidden within the implementation
 891                             of the standard <acronym>API</acronym> methods.
 892                         </entry>
 893                     </row>
 894
 895                     <row>
 896                         <entry><methodname>getType()</methodname></entry>
 897
 898                         <entry>
 899                             Returns a static class constant (e.g.
 900                             <constant>Zend_Feed_Reader::TYPE_ATOM_03</constant>,
 901                             i.e. Atom 0.3) indicating exactly what kind of feed
 902                             is being consumed.
 903                         </entry>
 904                     </row>
 905                 </tbody>
 906             </tgroup>
 907         </table>
 908     </sect2>
 909
 910     <sect2 id="zend.feed.reader.entry">
 911         <title>Retrieving Entry/Item Information</title>
 912
 913         <para>
 914             Retrieving information for specific entries or items (depending on
 915             whether you speak Atom or <acronym>RSS</acronym>) is identical to feed level data.
 916             Accessing entries is simply a matter of iterating over a Feed object
 917             or using the <acronym>SPL</acronym> <classname>Iterator</classname> interface Feed
 918             objects implement and calling the appropriate method on each.
 919         </para>
 920
 921         <table>
 922             <title>Entry Level API Methods</title>
 923
 924             <tgroup cols="2">
 925                 <tbody>
 926                     <row>
 927                         <entry><methodname>getId()</methodname></entry>
 928                         <entry>Returns a unique ID for the current entry.</entry>
 929                     </row>
 930
 931                     <row>
 932                         <entry><methodname>getTitle()</methodname></entry>
 933                         <entry>Returns the title of the current entry.</entry>
 934                     </row>
 935
 936                     <row>
 937                         <entry><methodname>getDescription()</methodname></entry>
 938                         <entry>Returns a description of the current entry.</entry>
 939                     </row>
 940
 941                     <row>
 942                         <entry><methodname>getLink()</methodname></entry>
 943
 944                         <entry>
 945                             Returns a <acronym>URI</acronym> to the <acronym>HTML</acronym> version
 946                             of the current entry.
 947                         </entry>
 948                     </row>
 949
 950                     <row>
 951                         <entry><methodname>getPermaLink()</methodname></entry>
 952
 953                         <entry>
 954                             Returns the permanent link to the current entry. In most cases,
 955                             this is the same as using <methodname>getLink()</methodname>.
 956                         </entry>
 957                     </row>
 958
 959                     <row>
 960                         <entry><methodname>getAuthors()</methodname></entry>
 961
 962                         <entry>
 963                             Returns an object of type
 964                             <classname>Zend_Feed_Reader_Collection_Author</classname> which is an
 965                             <classname>ArrayObject</classname> whose elements are each simple arrays
 966                             containing any combination of the keys "name", "email" and "uri". Where
 967                             irrelevant to the source data, some of these keys may be omitted.
 968                         </entry>
 969                     </row>
 970
 971                     <row>
 972                         <entry><methodname>getAuthor(integer $index = 0)</methodname></entry>
 973
 974                         <entry>
 975                             Returns either the first author known, or with the
 976                             optional <varname>$index</varname> parameter any specific
 977                             index on the array of Authors as described above (returning
 978                             <constant>NULL</constant> if an invalid index).
 979                         </entry>
 980                     </row>
 981
 982                     <row>
 983                         <entry><methodname>getDateCreated()</methodname></entry>
 984
 985                         <entry>
 986                             Returns the date on which the current entry was
 987                             created. Generally only applicable to Atom where it
 988                             represents the date the resource described by an
 989                             Atom 1.0 document was created.
 990                         </entry>
 991                     </row>
 992
 993                     <row>
 994                         <entry><methodname>getDateModified()</methodname></entry>
 995
 996                         <entry>
 997                             Returns the date on which the current entry was last
 998                             modified
 999                         </entry>
1000                     </row>
1001
1002                     <row>
1003                         <entry><methodname>getContent()</methodname></entry>
1004
1005                         <entry>
1006                             Returns the content of the current entry (this has any
1007                             entities reversed if possible assuming the content type is
1008                             <acronym>HTML</acronym>). The description is returned if a
1009                             separate content element does not exist.
1010                         </entry>
1011                     </row>
1012
1013                     <row>
1014                         <entry><methodname>getEnclosure()</methodname></entry>
1015
1016                         <entry>
1017                             Returns an array containing the value of all
1018                             attributes from a multi-media &lt;enclosure&gt; element including
1019                             as array keys: <emphasis>url</emphasis>,
1020                             <emphasis>length</emphasis>, <emphasis>type</emphasis>.
1021                             In accordance with the RSS Best Practices Profile of the RSS
1022                             Advisory Board, no support is offers for multiple enclosures
1023                             since such support forms no part of the RSS specification.
1024                         </entry>
1025                     </row>
1026
1027                     <row>
1028                         <entry><methodname>getCommentCount()</methodname></entry>
1029
1030                         <entry>
1031                             Returns the number of comments made on this entry at the
1032                             time the feed was last generated
1033                         </entry>
1034                     </row>
1035
1036                     <row>
1037                         <entry><methodname>getCommentLink()</methodname></entry>
1038
1039                         <entry>
1040                             Returns a <acronym>URI</acronym> pointing to the <acronym>HTML</acronym>
1041                             page where comments can be made on this entry
1042                         </entry>
1043                     </row>
1044
1045                     <row>
1046                         <entry>
1047                             <methodname>getCommentFeedLink([string $type =
1048                                 'atom'|'rss'])</methodname>
1049                         </entry>
1050
1051                         <entry>
1052                             Returns a <acronym>URI</acronym> pointing to a feed of the provided type
1053                             containing all comments for this entry (type defaults to
1054                             Atom/<acronym>RSS</acronym> depending on current feed type).
1055                         </entry>
1056                     </row>
1057
1058                     <row>
1059                         <entry><methodname>getCategories()</methodname></entry>
1060
1061                         <entry>
1062                             Returns a <classname>Zend_Feed_Reader_Collection_Category</classname>
1063                             object containing the details of any categories associated with the
1064                             entry. The supported fields include "term" (the machine readable
1065                             category name), "scheme" (the categorisation scheme/domain for this
1066                             category), and "label" (a <acronym>HTML</acronym> decoded human readable
1067                             category name). Where any of the three fields are absent from the field,
1068                             they are either set to the closest available alternative or, in the case
1069                             of "scheme", set to <constant>NULL</constant>.
1070                         </entry>
1071                     </row>
1072                 </tbody>
1073             </tgroup>
1074         </table>
1075
1076         <para>
1077             The extended <acronym>API</acronym> for entries is identical to that for feeds with the
1078             exception of the Iterator methods which are not needed here.
1079         </para>
1080
1081         <caution>
1082             <para>
1083                 There is often confusion over the concepts of modified and
1084                 created dates. In Atom, these are two clearly defined concepts
1085                 (so knock yourself out) but in <acronym>RSS</acronym> they are vague.
1086                 <acronym>RSS</acronym> 2.0
1087                 defines a single <emphasis>&lt;pubDate&gt;</emphasis> element
1088                 which typically refers to the date this entry was published,
1089                 i.e. a creation date of sorts. This is not always the case, and
1090                 it may change with updates or not. As a result, if you really
1091                 want to check whether an entry has changed, don't rely on the
1092                 results of <methodname>getDateModified()</methodname>. Instead,
1093                 consider tracking the <acronym>MD5</acronym> hash of three other elements
1094                 concatenated, e.g. using <methodname>getTitle()</methodname>,
1095                 <methodname>getDescription()</methodname> and
1096                 <methodname>getContent()</methodname>. If the entry was truly
1097                 updated, this hash computation will give a different result than
1098                 previously saved hashes for the same entry. This is obviously
1099                 content oriented, and will not assist in detecting changes to other
1100                 relevant elements. Atom feeds should not require such steps.
1101             </para>
1102
1103             <para>
1104                 Further muddying the
1105                 waters, dates in feeds may follow different standards. Atom and
1106                 Dublin Core dates should follow <acronym>ISO</acronym> 8601,
1107                 and <acronym>RSS</acronym> dates should
1108                 follow <acronym>RFC</acronym> 822 or <acronym>RFC</acronym> 2822
1109                 which is also common. Date methods
1110                 will throw an exception if <classname>Zend_Date</classname>
1111                 cannot load the date string using one of the above standards, or the
1112                 <acronym>PHP</acronym> recognised possibilities for <acronym>RSS</acronym> dates.
1113             </para>
1114         </caution>
1115
1116         <warning>
1117             <para>
1118                 The values returned from these methods are not validated. This
1119                 means users must perform validation on all retrieved data
1120                 including the filtering of any <acronym>HTML</acronym> such as from
1121                 <methodname>getContent()</methodname> before it is output from
1122                 your application. Remember that most feeds come from external
1123                 sources, and therefore the default assumption should be that
1124                 they cannot be trusted.
1125             </para>
1126         </warning>
1127
1128         <table>
1129             <title>Extended Entry Level API Methods</title>
1130
1131             <tgroup cols="2">
1132                 <tbody>
1133                     <row>
1134                         <entry><methodname>getDomDocument()</methodname></entry>
1135
1136                         <entry>
1137                             Returns the parent
1138                             <classname>DOMDocument</classname> object for the
1139                             entire feed (not just the current entry)
1140                         </entry>
1141                     </row>
1142
1143                     <row>
1144                         <entry><methodname>getElement()</methodname></entry>
1145
1146                         <entry>
1147                             Returns the current entry level
1148                             <classname>DOMElement</classname> object
1149                         </entry>
1150                     </row>
1151
1152                     <row>
1153                         <entry><methodname>getXpath()</methodname></entry>
1154
1155                         <entry>
1156                             Returns the <classname>DOMXPath</classname> object
1157                             used internally to run queries on the
1158                             <classname>DOMDocument</classname> object (this
1159                             includes core and Extension namespaces
1160                             pre-registered)
1161                         </entry>
1162                     </row>
1163
1164                     <row>
1165                         <entry><methodname>getXpathPrefix()</methodname></entry>
1166
1167                         <entry>
1168                             Returns the valid <acronym>DOM</acronym> path prefix prepended
1169                             to all XPath queries matching the entry being queried
1170                         </entry>
1171                     </row>
1172
1173                     <row>
1174                         <entry><methodname>getEncoding()</methodname></entry>
1175
1176                         <entry>
1177                             Returns the encoding of the source <acronym>XML</acronym> document
1178                             (note: this cannot account for errors such as the server sending
1179                             documents in a different encoding). The default encoding applied
1180                             in the absence of any other is the UTF-8 encoding of Unicode.
1181                         </entry>
1182                     </row>
1183
1184                     <row>
1185                         <entry><methodname>getExtensions()</methodname></entry>
1186
1187                         <entry>
1188                             Returns an array of all Extension objects loaded for
1189                             the current entry (note: both feed-level and entry-level
1190                             Extensions exist, and only entry-level Extensions are returned
1191                             here). The array keys are in the form {ExtensionName}_Entry.
1192                         </entry>
1193                     </row>
1194
1195                     <row>
1196                         <entry><methodname>getExtension(string $name)</methodname></entry>
1197
1198                         <entry>
1199                             Returns an Extension object for the entry registered under the
1200                             provided name. This allows more fine-grained access to
1201                             Extensions which may otherwise be hidden within the implementation
1202                             of the standard <acronym>API</acronym> methods.
1203                         </entry>
1204                     </row>
1205
1206                     <row>
1207                         <entry><methodname>getType()</methodname></entry>
1208
1209                         <entry>
1210                             Returns a static class constant (e.g.
1211                             <constant>Zend_Feed_Reader::TYPE_ATOM_03</constant>,
1212                             i.e. Atom 0.3) indicating exactly what kind
1213                             of feed is being consumed.
1214                         </entry>
1215                     </row>
1216                 </tbody>
1217             </tgroup>
1218         </table>
1219     </sect2>
1220
1221     <sect2 id="zend.feed.reader.extending">
1222         <title>Extending Feed and Entry APIs</title>
1223
1224         <para>
1225             Extending <classname>Zend_Feed_Reader</classname> allows you to add
1226             methods at both the feed and entry level which cover the retrieval
1227             of information not already supported by
1228             <classname>Zend_Feed_Reader</classname>. Given the number of
1229             <acronym>RSS</acronym> and
1230             Atom extensions that exist, this is a good thing since
1231             <classname>Zend_Feed_Reader</classname> couldn't possibly add
1232             everything.
1233         </para>
1234
1235         <para>
1236             There are two types of Extensions possible, those which retrieve
1237             information from elements which are immediate children of the root
1238             element (e.g. <command>&lt;channel&gt;</command> for <acronym>RSS</acronym> or
1239             <command>&lt;feed&gt;</command> for Atom) and those who retrieve
1240             information from child elements of an entry (e.g.
1241             <command>&lt;item&gt;</command> for <acronym>RSS</acronym> or
1242             <command>&lt;entry&gt;</command> for Atom). On the filesystem these are grouped as
1243             classes within a namespace based on the extension standard's name. For example,
1244             internally we have <classname>Zend_Feed_Reader_Extension_DublinCore_Feed</classname>
1245             and <classname>Zend_Feed_Reader_Extension_DublinCore_Entry</classname>
1246             classes which are two Extensions implementing Dublin Core
1247             1.0 and 1.1 support.
1248         </para>
1249
1250         <para>
1251             Extensions are loaded into <classname>Zend_Feed_Reader</classname>
1252             using <classname>Zend_Loader_PluginLoader</classname>, so their operation
1253             will be familiar from other Zend Framework components.
1254             <classname>Zend_Feed_Reader</classname> already bundles a number of
1255             these Extensions, however those which are not used internally and
1256             registered by default (so called Core Extensions) must be registered
1257             to <classname>Zend_Feed_Reader</classname> before they are used. The
1258             bundled Extensions include:
1259         </para>
1260
1261         <table>
1262             <title>Core Extensions (pre-registered)</title>
1263
1264             <tgroup cols="2">
1265                 <tbody>
1266                     <row>
1267                         <entry>DublinCore (Feed and Entry)</entry>
1268
1269                         <entry>
1270                             Implements support for Dublin Core Metadata Element Set 1.0 and 1.1
1271                         </entry>
1272                     </row>
1273
1274                     <row>
1275                         <entry>Content (Entry only)</entry>
1276                         <entry>Implements support for Content 1.0</entry>
1277                     </row>
1278
1279                     <row>
1280                         <entry>Atom (Feed and Entry)</entry>
1281                         <entry>Implements support for Atom 0.3 and Atom 1.0</entry>
1282                     </row>
1283
1284                     <row>
1285                         <entry>Slash</entry>
1286
1287                         <entry>
1288                             Implements support for the Slash <acronym>RSS</acronym> 1.0 module
1289                         </entry>
1290                     </row>
1291
1292                     <row>
1293                         <entry>WellFormedWeb</entry>
1294                         <entry>Implements support for the Well Formed Web CommentAPI 1.0</entry>
1295                     </row>
1296
1297                     <row>
1298                         <entry>Thread</entry>
1299
1300                         <entry>
1301                             Implements support for Atom Threading Extensions as described
1302                             in <acronym>RFC</acronym> 4685
1303                         </entry>
1304                     </row>
1305
1306                     <row>
1307                         <entry>Podcast</entry>
1308
1309                         <entry>
1310                             Implements support for the Podcast 1.0 <constant>DTD</constant> from
1311                             Apple
1312                         </entry>
1313                     </row>
1314                 </tbody>
1315             </tgroup>
1316         </table>
1317
1318         <para>
1319             The Core Extensions are somewhat special since they are extremely
1320             common and multi-faceted. For example, we have a Core Extension for Atom.
1321             Atom is implemented as an Extension (not just a base class) because it
1322             doubles as a valid <acronym>RSS</acronym> module - you can insert
1323             Atom elements into <acronym>RSS</acronym> feeds. I've even seen
1324             <acronym>RDF</acronym> feeds which use a lot of Atom in place of more
1325             common Extensions like Dublin Core.
1326         </para>
1327
1328         <table>
1329             <title>Non-Core Extensions (must register manually)</title>
1330
1331             <tgroup cols="2">
1332                 <tbody>
1333                     <row>
1334                         <entry>Syndication</entry>
1335
1336                         <entry>
1337                             Implements Syndication 1.0 support for <acronym>RSS</acronym> feeds
1338                         </entry>
1339                     </row>
1340
1341                     <row>
1342                         <entry>CreativeCommons</entry>
1343
1344                         <entry>
1345                             A <acronym>RSS</acronym> module that adds an element at the
1346                             &lt;channel&gt; or &lt;item&gt; level that specifies which Creative
1347                             Commons license applies.
1348                         </entry>
1349                     </row>
1350                 </tbody>
1351             </tgroup>
1352         </table>
1353
1354         <para>
1355             The additional non-Core Extensions are offered but not registered to
1356             <classname>Zend_Feed_Reader</classname> by default. If you want to
1357             use them, you'll need to tell
1358             <classname>Zend_Feed_Reader</classname> to load them in advance of
1359             importing a feed. Additional non-Core Extensions will be included
1360             in future iterations of the component.
1361         </para>
1362
1363         <para>
1364             Registering an Extension with
1365             <classname>Zend_Feed_Reader</classname>, so it is loaded and its <acronym>API</acronym>
1366             is available to Feed and Entry objects, is a simple affair using the
1367             <classname>Zend_Loader_PluginLoader</classname>. Here we register
1368             the optional Slash Extension, and discover that it can be directly
1369             called from the Entry level <acronym>API</acronym> without any effort. Note that
1370             Extension names are case sensitive and use camel casing for multiple
1371             terms.
1372         </para>
1373
1374         <programlisting language="php"><![CDATA[
1375 Zend_Feed_Reader::registerExtension('Syndication');
1376 $feed = Zend_Feed_Reader::import('http://rss.slashdot.org/Slashdot/slashdot');
1377 $updatePeriod = $feed->current()->getUpdatePeriod();
1378 ]]></programlisting>
1379
1380         <para>
1381             In the simple example above, we checked how frequently a feed is being updated
1382             using the <methodname>getUpdatePeriod()</methodname>
1383             method. Since it's not part of
1384             <classname>Zend_Feed_Reader</classname>'s core <acronym>API</acronym>, it could only be
1385             a method supported by the newly registered Syndication Extension.
1386         </para>
1387
1388         <para>
1389             As you can also notice, the new methods from Extensions are accessible from the main
1390             <acronym>API</acronym> using <acronym>PHP</acronym>'s magic methods. As an alternative,
1391             you can also directly access any Extension object for a similar result as seen below.
1392         </para>
1393
1394         <programlisting language="php"><![CDATA[
1395 Zend_Feed_Reader::registerExtension('Syndication');
1396 $feed = Zend_Feed_Reader::import('http://rss.slashdot.org/Slashdot/slashdot');
1397 $syndication = $feed->getExtension('Syndication');
1398 $updatePeriod = $syndication->getUpdatePeriod();
1399 ]]></programlisting>
1400
1401         <sect3 id="zend.feed.reader.extending.feed">
1402             <title>Writing Zend_Feed_Reader Extensions</title>
1403
1404             <para>
1405                 Inevitably, there will be times when the
1406                 <classname>Zend_Feed_Reader</classname> <acronym>API</acronym> is just not capable
1407                 of getting something you need from a feed or entry. You can use
1408                 the underlying source objects, like
1409                 <classname>DOMDocument</classname>, to get these by hand however
1410                 there is a more reusable method available by writing Extensions
1411                 supporting these new queries.
1412             </para>
1413
1414             <para>
1415                 As an example, let's take the case of a purely fictitious
1416                 corporation named Jungle Books. Jungle Books have been
1417                 publishing a lot of reviews on books they sell (from external
1418                 sources and customers), which are distributed as an <acronym>RSS</acronym> 2.0
1419                 feed. Their marketing department realises that web applications
1420                 using this feed cannot currently figure out exactly what book is
1421                 being reviewed. To make life easier for everyone, they determine
1422                 that the geek department needs to extend <acronym>RSS</acronym> 2.0 to include a
1423                 new element per entry supplying the <acronym>ISBN</acronym>-10 or
1424                 <acronym>ISBN</acronym>-13 number of
1425                 the publication the entry concerns. They define the new
1426                 <command>&lt;isbn&gt;</command> element quite simply with a standard
1427                 name and namespace <acronym>URI</acronym>:
1428             </para>
1429
1430             <programlisting language="php"><![CDATA[
1431 JungleBooks 1.0:
1432 http://example.com/junglebooks/rss/module/1.0/
1433 ]]></programlisting>
1434
1435             <para>
1436                 A snippet of <acronym>RSS</acronym> containing this extension in practice could be
1437                 something similar to:
1438             </para>
1439
1440             <programlisting language="php"><![CDATA[
1441 <?xml version="1.0" encoding="utf-8" ?>
1442 <rss version="2.0"
1443    xmlns:content="http://purl.org/rss/1.0/modules/content/"
1444    xmlns:jungle="http://example.com/junglebooks/rss/module/1.0/">
1445 <channel>
1446     <title>Jungle Books Customer Reviews</title>
1447     <link>http://example.com/junglebooks</link>
1448     <description>Many book reviews!</description>
1449     <pubDate>Fri, 26 Jun 2009 19:15:10 GMT</pubDate>
1450     <jungle:dayPopular>
1451         http://example.com/junglebooks/book/938
1452     </jungle:dayPopular>
1453     <item>
1454         <title>Review Of Flatland: A Romance of Many Dimensions</title>
1455         <link>http://example.com/junglebooks/review/987</link>
1456         <author>Confused Physics Student</author>
1457         <content:encoded>
1458         A romantic square?!
1459         </content:encoded>
1460         <pubDate>Thu, 25 Jun 2009 20:03:28 -0700</pubDate>
1461         <jungle:isbn>048627263X</jungle:isbn>
1462     </item>
1463 </channel>
1464 </rss>
1465 ]]></programlisting>
1466
1467             <para>
1468                 Implementing this new <acronym>ISBN</acronym> element as a simple entry level
1469                 extension would require the following class (using your own class
1470                 namespace outside of Zend).
1471             </para>
1472
1473             <programlisting language="php"><![CDATA[
1474 class My_FeedReader_Extension_JungleBooks_Entry
1475     extends Zend_Feed_Reader_Extension_EntryAbstract
1476 {
1477     public function getIsbn()
1478     {
1479         if (isset($this->_data['isbn'])) {
1480             return $this->_data['isbn'];
1481         }
1482         $isbn = $this->_xpath->evaluate(
1483             'string(' . $this->getXpathPrefix() . '/jungle:isbn)'
1484         );
1485         if (!$isbn) {
1486             $isbn = null;
1487         }
1488         $this->_data['isbn'] = $isbn;
1489         return $this->_data['isbn'];
1490     }
1491
1492     protected function _registerNamespaces()
1493     {
1494         $this->_xpath->registerNamespace(
1495             'jungle', 'http://example.com/junglebooks/rss/module/1.0/'
1496         );
1497     }
1498 }
1499 ]]></programlisting>
1500
1501             <para>
1502                 This extension is easy enough to follow. It creates a new method
1503                 <methodname>getIsbn()</methodname> which runs an XPath query on
1504                 the current entry to extract the <acronym>ISBN</acronym> number enclosed by the
1505                 <command>&lt;jungle:isbn&gt;</command> element. It can optionally
1506                 store this to the internal non-persistent cache (no need to keep
1507                 querying the <acronym>DOM</acronym> if it's called again on the same entry). The
1508                 value is returned to the caller. At the end we have a protected
1509                 method (it's abstract so it must exist) which registers the
1510                 Jungle Books namespace for their custom <acronym>RSS</acronym> module. While we
1511                 call this an <acronym>RSS</acronym> module, there's nothing to prevent the same
1512                 element being used in Atom feeds - and all Extensions which use
1513                 the prefix provided by <methodname>getXpathPrefix()</methodname>
1514                 are actually neutral and work on <acronym>RSS</acronym> or Atom feeds with no
1515                 extra code.
1516             </para>
1517
1518             <para>
1519                 Since this Extension is stored outside of Zend Framework, you'll
1520                 need to register the path prefix for your Extensions so
1521                 <classname>Zend_Loader_PluginLoader</classname> can find them.
1522                 After that, it's merely a matter of registering the Extension,
1523                 if it's not already loaded, and using it in practice.
1524             </para>
1525
1526             <programlisting language="php"><![CDATA[
1527 if(!Zend_Feed_Reader::isRegistered('JungleBooks')) {
1528     Zend_Feed_Reader::addPrefixPath(
1529         '/path/to/My/FeedReader/Extension', 'My_FeedReader_Extension'
1530     );
1531     Zend_Feed_Reader::registerExtension('JungleBooks');
1532 }
1533 $feed = Zend_Feed_Reader::import('http://example.com/junglebooks/rss');
1534
1535 // ISBN for whatever book the first entry in the feed was concerned with
1536 $firstIsbn = $feed->current()->getIsbn();
1537 ]]></programlisting>
1538
1539             <para>
1540                 Writing a feed level Extension is not much different. The
1541                 example feed from earlier included an unmentioned
1542                 <command>&lt;jungle:dayPopular&gt;</command> element which Jungle
1543                 Books have added to their standard to include a link to the
1544                 day's most popular book (in terms of visitor traffic). Here's
1545                 an Extension which adds a
1546                 <methodname>getDaysPopularBookLink()</methodname> method to the
1547                 feel level <acronym>API</acronym>.
1548             </para>
1549
1550             <programlisting language="php"><![CDATA[
1551 class My_FeedReader_Extension_JungleBooks_Feed
1552     extends Zend_Feed_Reader_Extension_FeedAbstract
1553 {
1554     public function getDaysPopularBookLink()
1555     {
1556         if (isset($this->_data['dayPopular'])) {
1557             return $this->_data['dayPopular'];
1558         }
1559         $dayPopular = $this->_xpath->evaluate(
1560             'string(' . $this->getXpathPrefix() . '/jungle:dayPopular)'
1561         );
1562         if (!$dayPopular) {
1563             $dayPopular = null;
1564         }
1565         $this->_data['dayPopular'] = $dayPopular;
1566         return $this->_data['dayPopular'];
1567     }
1568
1569     protected function _registerNamespaces()
1570     {
1571         $this->_xpath->registerNamespace(
1572             'jungle', 'http://example.com/junglebooks/rss/module/1.0/'
1573         );
1574     }
1575 }
1576 ]]></programlisting>
1577
1578             <para>
1579                 Let's repeat the last example using a custom Extension to show the
1580                 method being used.
1581             </para>
1582
1583             <programlisting language="php"><![CDATA[
1584 if(!Zend_Feed_Reader::isRegistered('JungleBooks')) {
1585     Zend_Feed_Reader::addPrefixPath(
1586         '/path/to/My/FeedReader/Extension', 'My_FeedReader_Extension'
1587     );
1588     Zend_Feed_Reader::registerExtension('JungleBooks');
1589 }
1590 $feed = Zend_Feed_Reader::import('http://example.com/junglebooks/rss');
1591
1592 // URI to the information page of the day's most popular book with visitors
1593 $daysPopularBookLink = $feed->getDaysPopularBookLink();
1594
1595 // ISBN for whatever book the first entry in the feed was concerned with
1596 $firstIsbn = $feed->current()->getIsbn();
1597 ]]></programlisting>
1598
1599             <para>
1600                 Going through these examples, you'll note that we don't register
1601                 feed and entry Extensions separately. Extensions within the same
1602                 standard may or may not include both a feed and entry class, so
1603                 <classname>Zend_Feed_Reader</classname> only requires you to
1604                 register the overall parent name, e.g. JungleBooks, DublinCore,
1605                 Slash. Internally, it can check at what level Extensions exist
1606                 and load them up if found. In our case, we have a full set of
1607                 Extensions now: <classname>JungleBooks_Feed</classname> and
1608                 <classname>JungleBooks_Entry</classname>.
1609             </para>
1610         </sect3>
1611     </sect2>
1612 </sect1>