1 <?xml version="1.0" encoding="UTF-8"?>
3 <sect1 id="zend.feed.importing">
4 <title>Importing Feeds</title>
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:
12 <programlisting language="php"><![CDATA[
13 $feed = Zend_Feed::import('http://feeds.example.com/feedName');
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:
21 <programlisting language="php"><![CDATA[
22 // importing a feed from a text file
23 $feedFromFile = Zend_Feed::importFile('feed.xml');
25 // importing a feed from a PHP string variable
26 $feedFromPHP = Zend_Feed::importString($feedString);
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.
39 <sect2 id="zend.feed.importing.custom">
40 <title>Custom feeds</title>
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>.
51 <sect3 id="zend.feed.importing.custom.importarray">
52 <title>Importing a custom array</title>
54 <programlisting language="php"><![CDATA[
55 // importing a feed from an array
56 $atomFeedFromArray = Zend_Feed::importArray($array);
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');
62 // importing a rss feed from an array
63 $rssFeedFromArray = Zend_Feed::importArray($array, 'rss');
67 The format of the array must conform to this structure:
70 <programlisting language="php"><![CDATA[
73 'title' => 'title of the feed',
74 'link' => 'canonical url to the feed',
77 'lastUpdate' => 'timestamp of the update date',
78 'published' => 'timestamp of the publication date',
81 'charset' => 'charset of the textual data',
84 'description' => 'short description of the feed',
85 'author' => 'author/publisher of the feed',
86 'email' => 'email of the author',
88 // optional, ignored if atom is used
89 'webmaster' => 'email address for person responsible '
90 . 'for technical issues',
93 'copyright' => 'copyright notice',
94 'image' => 'url to image',
95 'generator' => 'generator',
96 'language' => 'language the feed is written in',
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.',
103 // optional, ignored if atom is used
104 // a cloud to be notified of updates
107 'domain' => 'domain of the cloud, e.g. rpc.sys.com',
109 // optional, defaults to 80
110 'port' => 'port to connect to',
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'
118 // optional, ignored if atom is used
119 // a text input box that can be displayed with the feed
120 'textInput' => array(
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'
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
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
145 // optional, ignored if atom is used
146 // Itunes extension data
148 // optional, default to the main author value
149 'author' => 'Artist column',
151 // optional, default to the main author value
152 // Owner of the podcast
154 'name' => 'name of the owner',
155 'email' => 'email of the owner'
158 // optional, default to the main image value
159 'image' => 'album/podcast art',
161 // optional, default to the main description value
162 'subtitle' => 'short description',
163 'summary' => 'longer description',
166 'block' => 'Prevent an episode from appearing (yes|no)',
168 // required, Category column and in iTunes Music Store Browse
173 'main' => 'main category',
176 'sub' => 'sub category'
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'
189 'title' => 'title of the feed entry',
190 'link' => 'url to a feed entry',
192 // required, only text, no html
193 'description' => 'short version of a feed entry',
196 'guid' => 'id of the article, '
197 . 'if not given link value will used',
199 // optional, can contain html
200 'content' => 'long version',
203 'lastUpdate' => 'timestamp of the publication date',
204 'comments' => 'comments page of the feed entry',
205 'commentRss' => 'the feed url of the associated comments',
207 // optional, original source of the feed entry
210 'title' => 'title of the original source',
211 'url' => 'url of the original source'
214 // optional, list of the attached categories
218 'term' => 'first category label',
221 'scheme' => 'url that identifies a categorization scheme'
225 // data for the second category and so on
229 // optional, list of the enclosures of the feed entry
230 'enclosure' => array(
233 'url' => 'url of the linked enclosure',
236 'type' => 'mime type of the enclosure',
237 'length' => 'length of the linked content in octets'
241 //data for the second enclosure and so on
247 //data for the second entry and so on
260 <acronym>RSS</acronym> 2.0 specification: <ulink
261 url="http://blogs.law.harvard.edu/tech/rss">RSS 2.0</ulink>
267 Atom specification: <ulink
268 url="http://tools.ietf.org/html/rfc4287">RFC 4287</ulink>
274 <acronym>WFW</acronym> specification: <ulink
275 url="http://wellformedweb.org/news/wfw_namespace_elements">Well
282 iTunes specification: <ulink
283 url="http://www.apple.com/itunes/store/podcaststechspecs.html">iTunes
284 Technical Specifications</ulink>
290 <sect3 id="zend.feed.importing.custom.importbuilder">
291 <title>Importing a custom data source</title>
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.
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>.
317 Here is an example of <methodname>Zend_Feed::importBuilder()</methodname> usage:
320 <programlisting language="php"><![CDATA[
321 // importing a feed from a custom builder source
323 Zend_Feed::importBuilder(new Zend_Feed_Builder($array));
325 // the following line is equivalent to the above;
326 // by default a Zend_Feed_Atom instance is returned
328 Zend_Feed::importBuilder(new Zend_Feed_Builder($array), 'atom');
330 // importing a rss feed from a custom builder array
332 Zend_Feed::importBuilder(new Zend_Feed_Builder($array), 'rss');
336 <sect3 id="zend.feed.importing.custom.dump">
337 <title>Dumping the contents of a feed</title>
340 To dump the contents of a <classname>Zend_Feed_Abstract</classname> instance, you
341 may use <methodname>send()</methodname> or <methodname>saveXml()</methodname>
345 <programlisting language="php"><![CDATA[
346 assert($feed instanceof Zend_Feed_Abstract);
348 // dump the feed to standard output
349 print $feed->saveXML();
351 // send http headers and dump the feed