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

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="zend.feed.importing">
   4     <title>Importing Feeds</title>
   5
   6     <para>
   7         <classname>Zend_Feed</classname> enables developers to retrieve feeds very easily. If you
   8         know the <acronym>URI</acronym> of a feed, simply use the
   9         <methodname>Zend_Feed::import()</methodname> method:
  10     </para>
  11
  12     <programlisting language="php"><![CDATA[
  13 $feed = Zend_Feed::import('http://feeds.example.com/feedName');
  14 ]]></programlisting>
  15
  16     <para>
  17         You can also use <classname>Zend_Feed</classname> to fetch the contents of a feed from a
  18         file or the contents of a <acronym>PHP</acronym> string variable:
  19     </para>
  20
  21     <programlisting language="php"><![CDATA[
  22 // importing a feed from a text file
  23 $feedFromFile = Zend_Feed::importFile('feed.xml');
  24
  25 // importing a feed from a PHP string variable
  26 $feedFromPHP = Zend_Feed::importString($feedString);
  27 ]]></programlisting>
  28
  29     <para>
  30         In each of the examples above, an object of a class that extends
  31         <classname>Zend_Feed_Abstract</classname> is returned upon success, depending on the type of
  32         the feed. If an <acronym>RSS</acronym> feed were retrieved via one of the import methods
  33         above, then a <classname>Zend_Feed_Rss</classname> object would be returned. On the other
  34         hand, if an Atom feed were imported, then a <classname>Zend_Feed_Atom</classname> object is
  35         returned. The import methods will also throw a <classname>Zend_Feed_Exception</classname>
  36         object upon failure, such as an unreadable or malformed feed.
  37     </para>
  38
  39     <sect2 id="zend.feed.importing.custom">
  40         <title>Custom feeds</title>
  41
  42         <para>
  43             <classname>Zend_Feed</classname> enables developers to create custom feeds very easily.
  44             You just have to create an array and to import it with <classname>Zend_Feed</classname>.
  45             This array can be imported with <methodname>Zend_Feed::importArray()</methodname> or
  46             with <methodname>Zend_Feed::importBuilder()</methodname>. In this last case the array
  47             will be computed on the fly by a custom data source implementing
  48             <classname>Zend_Feed_Builder_Interface</classname>.
  49         </para>
  50
  51         <sect3 id="zend.feed.importing.custom.importarray">
  52             <title>Importing a custom array</title>
  53
  54             <programlisting language="php"><![CDATA[
  55 // importing a feed from an array
  56 $atomFeedFromArray = Zend_Feed::importArray($array);
  57
  58 // the following line is equivalent to the above;
  59 // by default a Zend_Feed_Atom instance is returned
  60 $atomFeedFromArray = Zend_Feed::importArray($array, 'atom');
  61
  62 // importing a rss feed from an array
  63 $rssFeedFromArray = Zend_Feed::importArray($array, 'rss');
  64 ]]></programlisting>
  65
  66             <para>
  67                 The format of the array must conform to this structure:
  68             </para>
  69
  70             <programlisting language="php"><![CDATA[
  71 array(
  72     //required
  73     'title' => 'title of the feed',
  74     'link'  => 'canonical url to the feed',
  75
  76     // optional
  77     'lastUpdate' => 'timestamp of the update date',
  78     'published'  => 'timestamp of the publication date',
  79
  80     // required
  81     'charset' => 'charset of the textual data',
  82
  83     // optional
  84     'description' => 'short description of the feed',
  85     'author'      => 'author/publisher of the feed',
  86     'email'       => 'email of the author',
  87
  88     // optional, ignored if atom is used
  89     'webmaster' => 'email address for person responsible '
  90                 .  'for technical issues',
  91
  92     // optional
  93     'copyright' => 'copyright notice',
  94     'image'     => 'url to image',
  95     'generator' => 'generator',
  96     'language'  => 'language the feed is written in',
  97
  98     // optional, ignored if atom is used
  99     'ttl'    => 'how long in minutes a feed can be cached '
 100              .  'before refreshing',
 101     'rating' => 'The PICS rating for the channel.',
 102
 103     // optional, ignored if atom is used
 104     // a cloud to be notified of updates
 105     'cloud'       => array(
 106         // required
 107         'domain' => 'domain of the cloud, e.g. rpc.sys.com',
 108
 109         // optional, defaults to 80
 110         'port' => 'port to connect to',
 111
 112         // required
 113         'path'              => 'path of the cloud, e.g. /RPC2',
 114         'registerProcedure' => 'procedure to call, e.g. myCloud.rssPlsNotify',
 115         'protocol'          => 'protocol to use, e.g. soap or xml-rpc'
 116     ),
 117
 118     // optional, ignored if atom is used
 119     // a text input box that can be displayed with the feed
 120     'textInput'   => array(
 121         // required
 122         'title'       => 'label of the Submit button in the text input area',
 123         'description' => 'explains the text input area',
 124         'name'        => 'the name of the text object in the text input area',
 125         'link'        => 'URL of the CGI script processing text input requests'
 126     ),
 127
 128     // optional, ignored if atom is used
 129     // Hint telling aggregators which hours they can skip
 130     'skipHours' => array(
 131         // up to 24 rows whose value is a number between 0 and 23
 132         // e.g 13 (1pm)
 133         'hour in 24 format'
 134     ),
 135
 136     // optional, ignored if atom is used
 137     // Hint telling aggregators which days they can skip
 138     'skipDays ' => array(
 139         // up to 7 rows whose value is
 140         // Monday, Tuesday, Wednesday, Thursday, Friday, Saturday or Sunday
 141         // e.g Monday
 142         'a day to skip'
 143     ),
 144
 145     // optional, ignored if atom is used
 146     // Itunes extension data
 147     'itunes' => array(
 148         // optional, default to the main author value
 149         'author' => 'Artist column',
 150
 151         // optional, default to the main author value
 152         // Owner of the podcast
 153         'owner' => array(
 154             'name'  => 'name of the owner',
 155             'email' => 'email of the owner'
 156         ),
 157
 158         // optional, default to the main image value
 159         'image' => 'album/podcast art',
 160
 161         // optional, default to the main description value
 162         'subtitle' => 'short description',
 163         'summary'  => 'longer description',
 164
 165         // optional
 166         'block' => 'Prevent an episode from appearing (yes|no)',
 167
 168         // required, Category column and in iTunes Music Store Browse
 169         'category' => array(
 170             // up to 3 rows
 171             array(
 172                 // required
 173                 'main' => 'main category',
 174
 175                 // optional
 176                 'sub'  => 'sub category'
 177             )
 178         ),
 179
 180         // optional
 181         'explicit'     => 'parental advisory graphic (yes|no|clean)',
 182         'keywords'     => 'a comma separated list of 12 keywords maximum',
 183         'new-feed-url' => 'used to inform iTunes of new feed URL location'
 184     ),
 185
 186     'entries' => array(
 187         array(
 188             //required
 189             'title' => 'title of the feed entry',
 190             'link'  => 'url to a feed entry',
 191
 192             // required, only text, no html
 193             'description' => 'short version of a feed entry',
 194
 195             // optional
 196             'guid' => 'id of the article, '
 197                    .  'if not given link value will used',
 198
 199             // optional, can contain html
 200             'content' => 'long version',
 201
 202             // optional
 203             'lastUpdate' => 'timestamp of the publication date',
 204             'comments'   => 'comments page of the feed entry',
 205             'commentRss' => 'the feed url of the associated comments',
 206
 207             // optional, original source of the feed entry
 208             'source' => array(
 209                 // required
 210                 'title' => 'title of the original source',
 211                 'url'   => 'url of the original source'
 212             ),
 213
 214             // optional, list of the attached categories
 215             'category' => array(
 216                 array(
 217                     // required
 218                     'term' => 'first category label',
 219
 220                     // optional
 221                     'scheme' => 'url that identifies a categorization scheme'
 222                 ),
 223
 224                 array(
 225                     // data for the second category and so on
 226                 )
 227             ),
 228
 229             // optional, list of the enclosures of the feed entry
 230             'enclosure'    => array(
 231                 array(
 232                     // required
 233                     'url' => 'url of the linked enclosure',
 234
 235                     // optional
 236                     'type' => 'mime type of the enclosure',
 237                     'length' => 'length of the linked content in octets'
 238                 ),
 239
 240                 array(
 241                     //data for the second enclosure and so on
 242                 )
 243             )
 244         ),
 245
 246         array(
 247             //data for the second entry and so on
 248         )
 249     )
 250 );
 251 ]]></programlisting>
 252
 253             <para>
 254                 References:
 255             </para>
 256
 257             <itemizedlist>
 258                 <listitem>
 259                     <para>
 260                         <acronym>RSS</acronym> 2.0 specification: <ulink
 261                             url="http://blogs.law.harvard.edu/tech/rss">RSS 2.0</ulink>
 262                     </para>
 263                 </listitem>
 264
 265                 <listitem>
 266                     <para>
 267                         Atom specification: <ulink
 268                             url="http://tools.ietf.org/html/rfc4287">RFC 4287</ulink>
 269                     </para>
 270                 </listitem>
 271
 272                 <listitem>
 273                     <para>
 274                         <acronym>WFW</acronym> specification: <ulink
 275                             url="http://wellformedweb.org/news/wfw_namespace_elements">Well
 276                             Formed Web</ulink>
 277                     </para>
 278                 </listitem>
 279
 280                 <listitem>
 281                     <para>
 282                         iTunes specification: <ulink
 283                             url="http://www.apple.com/itunes/store/podcaststechspecs.html">iTunes
 284                             Technical Specifications</ulink>
 285                     </para>
 286                 </listitem>
 287             </itemizedlist>
 288         </sect3>
 289
 290         <sect3 id="zend.feed.importing.custom.importbuilder">
 291             <title>Importing a custom data source</title>
 292
 293             <para>
 294                 You can create a <classname>Zeed_Feed</classname> instance from any data source
 295                 implementing <classname>Zend_Feed_Builder_Interface</classname>. You just have to
 296                 implement the <methodname>getHeader()</methodname> and
 297                 <methodname>getEntries()</methodname> methods to be able to use your object with
 298                 <methodname>Zend_Feed::importBuilder()</methodname>. As a simple reference
 299                 implementation, you can use <classname>Zend_Feed_Builder</classname>, which takes
 300                 an array in its constructor, performs some minor validation, and then can be used
 301                 in the <methodname>importBuilder()</methodname> method. The
 302                 <methodname>getHeader()</methodname> method must return an instance of
 303                 <classname>Zend_Feed_Builder_Header</classname>, and
 304                 <methodname>getEntries()</methodname> must return an array of
 305                 <classname>Zend_Feed_Builder_Entry</classname> instances.
 306             </para>
 307
 308             <note>
 309                 <para>
 310                     <classname>Zend_Feed_Builder</classname> serves as a concrete implementation to
 311                     demonstrate the usage. Users are encouraged to make their own classes to
 312                     implement <classname>Zend_Feed_Builder_Interface</classname>.
 313                 </para>
 314             </note>
 315
 316             <para>
 317                 Here is an example of <methodname>Zend_Feed::importBuilder()</methodname> usage:
 318             </para>
 319
 320             <programlisting language="php"><![CDATA[
 321 // importing a feed from a custom builder source
 322 $atomFeedFromArray =
 323     Zend_Feed::importBuilder(new Zend_Feed_Builder($array));
 324
 325 // the following line is equivalent to the above;
 326 // by default a Zend_Feed_Atom instance is returned
 327 $atomFeedFromArray =
 328     Zend_Feed::importBuilder(new Zend_Feed_Builder($array), 'atom');
 329
 330 // importing a rss feed from a custom builder array
 331 $rssFeedFromArray =
 332     Zend_Feed::importBuilder(new Zend_Feed_Builder($array), 'rss');
 333 ]]></programlisting>
 334         </sect3>
 335
 336         <sect3 id="zend.feed.importing.custom.dump">
 337             <title>Dumping the contents of a feed</title>
 338
 339             <para>
 340                 To dump the contents of a <classname>Zend_Feed_Abstract</classname> instance, you
 341                 may use <methodname>send()</methodname> or <methodname>saveXml()</methodname>
 342                 methods.
 343             </para>
 344
 345             <programlisting language="php"><![CDATA[
 346 assert($feed instanceof Zend_Feed_Abstract);
 347
 348 // dump the feed to standard output
 349 print $feed->saveXML();
 350
 351 // send http headers and dump the feed
 352 $feed->send();
 353 ]]></programlisting>
 354         </sect3>
 355     </sect2>
 356 </sect1>
 357 <!--
 358 vim:se ts=4 sw=4 et:
 359 -->