Importing Feeds

Zend_Feed enables developers to retrieve feeds very easily. If you know the URI of a feed, simply use the Zend_Feed::import() method:

  1. $feed = Zend_Feed::import('http://feeds.example.com/feedName');

You can also use Zend_Feed to fetch the contents of a feed from a file or the contents of a PHP string variable:

  1. // importing a feed from a text file
  2. $feedFromFile = Zend_Feed::importFile('feed.xml');
  3.  
  4. // importing a feed from a PHP string variable
  5. $feedFromPHP = Zend_Feed::importString($feedString);

In each of the examples above, an object of a class that extends Zend_Feed_Abstract is returned upon success, depending on the type of the feed. If an RSS feed were retrieved via one of the import methods above, then a Zend_Feed_Rss object would be returned. On the other hand, if an Atom feed were imported, then a Zend_Feed_Atom object is returned. The import methods will also throw a Zend_Feed_Exception object upon failure, such as an unreadable or malformed feed.

Custom feeds

Zend_Feed enables developers to create custom feeds very easily. You just have to create an array and to import it with Zend_Feed. This array can be imported with Zend_Feed::importArray() or with Zend_Feed::importBuilder(). In this last case the array will be computed on the fly by a custom data source implementing Zend_Feed_Builder_Interface.

Importing a custom array

  1. // importing a feed from an array
  2. $atomFeedFromArray = Zend_Feed::importArray($array);
  3.  
  4. // the following line is equivalent to the above;
  5. // by default a Zend_Feed_Atom instance is returned
  6. $atomFeedFromArray = Zend_Feed::importArray($array, 'atom');
  7.  
  8. // importing a rss feed from an array
  9. $rssFeedFromArray = Zend_Feed::importArray($array, 'rss');

The format of the array must conform to this structure:

  1.     //required
  2.     'title' => 'title of the feed',
  3.     'link'  => 'canonical url to the feed',
  4.  
  5.     // optional
  6.     'lastUpdate' => 'timestamp of the update date',
  7.     'published'  => 'timestamp of the publication date',
  8.  
  9.     // required
  10.     'charset' => 'charset of the textual data',
  11.  
  12.     // optional
  13.     'description' => 'short description of the feed',
  14.     'author'      => 'author/publisher of the feed',
  15.     'email'       => 'email of the author',
  16.  
  17.     // optional, ignored if atom is used
  18.     'webmaster' => 'email address for person responsible '
  19.                 .  'for technical issues',
  20.  
  21.     // optional
  22.     'copyright' => 'copyright notice',
  23.     'image'     => 'url to image',
  24.     'generator' => 'generator',
  25.     'language'  => 'language the feed is written in',
  26.  
  27.     // optional, ignored if atom is used
  28.     'ttl'    => 'how long in minutes a feed can be cached '
  29.              .  'before refreshing',
  30.     'rating' => 'The PICS rating for the channel.',
  31.  
  32.     // optional, ignored if atom is used
  33.     // a cloud to be notified of updates
  34.     'cloud'       => array(
  35.         // required
  36.         'domain' => 'domain of the cloud, e.g. rpc.sys.com',
  37.  
  38.         // optional, defaults to 80
  39.         'port' => 'port to connect to',
  40.  
  41.         // required
  42.         'path'              => 'path of the cloud, e.g. /RPC2',
  43.         'registerProcedure' => 'procedure to call, e.g. myCloud.rssPlsNotify',
  44.         'protocol'          => 'protocol to use, e.g. soap or xml-rpc'
  45.     ),
  46.  
  47.     // optional, ignored if atom is used
  48.     // a text input box that can be displayed with the feed
  49.     'textInput'   => array(
  50.         // required
  51.         'title'       => 'label of the Submit button in the text input area',
  52.         'description' => 'explains the text input area',
  53.         'name'        => 'the name of the text object in the text input area',
  54.         'link'        => 'URL of the CGI script processing text input requests'
  55.     ),
  56.  
  57.     // optional, ignored if atom is used
  58.     // Hint telling aggregators which hours they can skip
  59.     'skipHours' => array(
  60.         // up to 24 rows whose value is a number between 0 and 23
  61.         // e.g 13 (1pm)
  62.         'hour in 24 format'
  63.     ),
  64.  
  65.     // optional, ignored if atom is used
  66.     // Hint telling aggregators which days they can skip
  67.     'skipDays ' => array(
  68.         // up to 7 rows whose value is
  69.         // Monday, Tuesday, Wednesday, Thursday, Friday, Saturday or Sunday
  70.         // e.g Monday
  71.         'a day to skip'
  72.     ),
  73.  
  74.     // optional, ignored if atom is used
  75.     // Itunes extension data
  76.     'itunes' => array(
  77.         // optional, default to the main author value
  78.         'author' => 'Artist column',
  79.  
  80.         // optional, default to the main author value
  81.         // Owner of the podcast
  82.         'owner' => array(
  83.             'name'  => 'name of the owner',
  84.             'email' => 'email of the owner'
  85.         ),
  86.  
  87.         // optional, default to the main image value
  88.         'image' => 'album/podcast art',
  89.  
  90.         // optional, default to the main description value
  91.         'subtitle' => 'short description',
  92.         'summary'  => 'longer description',
  93.  
  94.         // optional
  95.         'block' => 'Prevent an episode from appearing (yes|no)',
  96.  
  97.         // required, Category column and in iTunes Music Store Browse
  98.         'category' => array(
  99.             // up to 3 rows
  100.             array(
  101.                 // required
  102.                 'main' => 'main category',
  103.  
  104.                 // optional
  105.                 'sub'  => 'sub category'
  106.             )
  107.         ),
  108.  
  109.         // optional
  110.         'explicit'     => 'parental advisory graphic (yes|no|clean)',
  111.         'keywords'     => 'a comma separated list of 12 keywords maximum',
  112.         'new-feed-url' => 'used to inform iTunes of new feed URL location'
  113.     ),
  114.  
  115.     'entries' => array(
  116.         array(
  117.             //required
  118.             'title' => 'title of the feed entry',
  119.             'link'  => 'url to a feed entry',
  120.  
  121.             // required, only text, no html
  122.             'description' => 'short version of a feed entry',
  123.  
  124.             // optional
  125.             'guid' => 'id of the article, '
  126.                    .  'if not given link value will used',
  127.  
  128.             // optional, can contain html
  129.             'content' => 'long version',
  130.  
  131.             // optional
  132.             'lastUpdate' => 'timestamp of the publication date',
  133.             'comments'   => 'comments page of the feed entry',
  134.             'commentRss' => 'the feed url of the associated comments',
  135.  
  136.             // optional, original source of the feed entry
  137.             'source' => array(
  138.                 // required
  139.                 'title' => 'title of the original source',
  140.                 'url'   => 'url of the original source'
  141.             ),
  142.  
  143.             // optional, list of the attached categories
  144.             'category' => array(
  145.                 array(
  146.                     // required
  147.                     'term' => 'first category label',
  148.  
  149.                     // optional
  150.                     'scheme' => 'url that identifies a categorization scheme'
  151.                 ),
  152.  
  153.                 array(
  154.                     // data for the second category and so on
  155.                 )
  156.             ),
  157.  
  158.             // optional, list of the enclosures of the feed entry
  159.             'enclosure'    => array(
  160.                 array(
  161.                     // required
  162.                     'url' => 'url of the linked enclosure',
  163.  
  164.                     // optional
  165.                     'type' => 'mime type of the enclosure',
  166.                     'length' => 'length of the linked content in octets'
  167.                 ),
  168.  
  169.                 array(
  170.                     //data for the second enclosure and so on
  171.                 )
  172.             )
  173.         ),
  174.  
  175.         array(
  176.             //data for the second entry and so on
  177.         )
  178.     )
  179. );

References:

Importing a custom data source

You can create a Zeed_Feed instance from any data source implementing Zend_Feed_Builder_Interface. You just have to implement the getHeader() and getEntries() methods to be able to use your object with Zend_Feed::importBuilder(). As a simple reference implementation, you can use Zend_Feed_Builder, which takes an array in its constructor, performs some minor validation, and then can be used in the importBuilder() method. The getHeader() method must return an instance of Zend_Feed_Builder_Header, and getEntries() must return an array of Zend_Feed_Builder_Entry instances.

Note: Zend_Feed_Builder serves as a concrete implementation to demonstrate the usage. Users are encouraged to make their own classes to implement Zend_Feed_Builder_Interface.

Here is an example of Zend_Feed::importBuilder() usage:

  1. // importing a feed from a custom builder source
  2. $atomFeedFromArray =
  3.     Zend_Feed::importBuilder(new Zend_Feed_Builder($array));
  4.  
  5. // the following line is equivalent to the above;
  6. // by default a Zend_Feed_Atom instance is returned
  7. $atomFeedFromArray =
  8.     Zend_Feed::importBuilder(new Zend_Feed_Builder($array), 'atom');
  9.  
  10. // importing a rss feed from a custom builder array
  11. $rssFeedFromArray =
  12.     Zend_Feed::importBuilder(new Zend_Feed_Builder($array), 'rss');

Dumping the contents of a feed

To dump the contents of a Zend_Feed_Abstract instance, you may use send() or saveXml() methods.

  1. assert($feed instanceof Zend_Feed_Abstract);
  2.  
  3. // dump the feed to standard output
  4. print $feed->saveXML();
  5.  
  6. // send http headers and dump the feed
  7. $feed->send();
blog comments powered by Disqus