Introduction | Zend_Feed Programmer's Reference Guide | Retrieving Feeds from Web Pages

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

References:

- RSS 2.0 specification: » RSS 2.0

- Atom specification: » RFC 4287

- WFW specification: » Well Formed Web

- iTunes specification: » iTunes Technical Specifications

# 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));
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');
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);
3. // dump the feed to standard output
4. print $feed->saveXML();
6. // send http headers and dump the feed
7. $feed->send();

Introduction | Zend_Feed Programmer's Reference Guide | Retrieving Feeds from Web Pages