Zeta Components - high quality PHP components

• Tutorial
• API
• Specifications

eZ Components - Feed

Introduction

Description

The purpose of the Feed component is to handle parsing and creating RSS and ATOM feeds.

XML feeds overview

XML feeds

An XML feed is an XML document with a certain structure, which lists a series of entries or items.

An example XML feed:

This XML document describes an RSS2 feed, with channel elements title, link, description, language, pubDate and webMaster. The XML document also contains 2 entries (item), each one with the elements title, link, description, pubDate and guid. These elements are not the only ones present in RSS2 feeds, and some elements are not required to be present.

The Feed document allows creating and parsing such XML documents. The feed types supported by the Feed component are ATOM, RSS1 and RSS2.

Modules

XML feeds are extensible through modules. A module has a namespace and certain XML elements. An example of a feed module is iTunes, which allows creating and parsing podcasts for the iTunes media player.

Example of feed (podcast) with the iTunes module:

The elements of the iTunes module are the ones with itunes: in the element name. They describe the feed (subtitle, author, summary, image, category) and the items (called episodes) in the feed (author, subtitle, summary, duration, keywords). These iTunes elements are not the only ones present in iTunes podcasts.

Applications

XML feeds can be used in many applications:

• content aggregation - blogs or journals can provide their content in an XML feed form. Subscribers to a feed are able to view content aggregated from multiple websites in one location, using an aggregator software program.

• news - websites can provide news in a feed format. The advantage is that users do not need to check a website or subscribe to newsletters, but instead can have news from multiple sources in their aggregator program.

• podcasts - XML feeds can have enclosures, which are links to media files (audio, video, pdf, etc). Some aggregator programs or the iTunes media player can download automatically these media files when they become available.

Class overview

An overview of the most important classes in the Feed component.

Base classes

ezcFeed

Defines a feed object of a specified type. Can be created from scratch or from an existing XML document (with autodetection of type). It can be generated into an XML document.

ezcFeedElement

Base class for all feed element types.

ezcFeedModule

Base class for all feed modules.

Supported feed types

A feed has a type (eg. RSS1, RSS2 or ATOM). The feed type defines which processor is used to parse and generate that type. The following feed processors are supported by the Feed component:

• ATOM (ezcFeedAtom) - RFC 4287

• RSS1 (ezcFeedRss1) - (RDF Site Summary) Specifications

• RSS2 (ezcFeedRss2) - (Really Simple Syndication) - Specifications

A new processor can be defined by creating a class which extends the class ezcFeedProcessor and implements the interface ezcFeedParser. The new class needs to be added to the supported feed types list by calling the ezcFeed::registerFeed() function.

Supported feed modules

The following modules are supported by the Feed component:

• Content (ezcFeedContentModule) - Specifications

• CreativeCommons (ezcFeedCreativeCommonsModule) - Specifications

• DublinCore (ezcFeedDublinCoreModule) - Specifications

• Geo (ezcFeedGeoModule) - Specifications

• iTunes (ezcFeedITunesModule) - Specifications

A new module can be defined by creating a class which extends the class ezcFeedModule. The new class needs to be added to the supported modules list by calling the ezcFeed::registerModule() function.

Feed element types

The following element types are implemented in the Feed component (extending the class ezcFeedElement):

• item (ezcFeedEntryElement) - specifies a feed item (entry) with the sub-elements author, category, comments, content, contributor, copyright, description, enclosure, id, link, published, title, updated, source

• category (ezcFeedCategoryElement) - specifies a category with the attributes term, scheme, label and category (for iTunes subcategories).

• cloud (ezcFeedCloudElement) - specifies an RSS2 cloud element with the attributes domain, port, path, registerProcedure, protocol

• content (ezcFeedContentElement) - specifies an ATOM content element with the attributes text, type, language, src

• date (ezcFeedDateElement) - specifies a date element with the attribute date. The date is stored as a DateTime object (assigning an integer timestamp or a formatted date works as well)

• enclosure (ezcFeedEnclosureElement) - specifies an RSS2 enclosure element with the attributes url, type, length. Converted to an ezcFeedLinkElement when generating an ATOM feed.

• generator (ezcFeedGeneratorElement) - specifies a generator element with the attributes name, url, version

• id (ezcFeedIdElement) - specifies an identifier element with the attributes id, isPermaLink

• image (ezcFeedImageElement) - specifies an image with the attributes link, title, url (RSS1 and RSS2), description, width, height (RSS2 only), about (RSS1 only)

• language (ezcFeedTextElement) - specifies a language for the feed, one of RSS language codes. It is rendered as an xml:lang attribute in XML for ATOM and RSS1 feeds, and as a language element for RSS2 feeds. For item elements it will always be rendered as an xml:lang attribute in all feed types.

• link (ezcFeedLinkElement) - specifies a link with the attributes href, rel, hreflang, title, type, length

• person (ezcFeedPersonElement) - specifies a person with the attributes name, email, uri (ATOM only)

• skipDays (ezcFeedSkipDaysElement) - specifies an RSS2 skipDays element with the attributes days

• skipHours (ezcFeedSkipHoursElement) - specifies an RSS2 skipHours element with the attributes hours

• source (ezcFeedSourceElement) - specifies a source element with the RSS2 attributes source and url, and ATOM elements title, description, copyright, author, contributor, updated, generator, image, icon, id, link, category

• text (ezcFeedTextElement) - specifies a text with the attributes text, type (ATOM only), language (ATOM only)

• textInput (ezcFeedTextInputElement) - specifies an RSS1 and RSS2 text input element with the attributes name, link, title, description, about (RSS1 only)

Assigning values to feed elements should be done in a way that will not break the resulting XML document. In other words, encoding of special characters to HTML entities is not done by default, and the developer is responsible with calling htmlentities() himself when assigning values to feed elements. Example: if the feed title contains the & character, it is the responsability of the developer to encode it properly as &.

How to create a feed

This part of the tutorial will show you step by step how to create an RSS2 feed which handles the news on a website. Creating an ATOM or RSS1 is similar, although some code needs to be changed. See the Feed creator example for a sample application which can be used to create simple XML feeds of any type (ATOM, RSS1 or RSS2) by providing a simple text file as input.

The information which we want to show in the feed is:

• the title of the feed: eZ news feed

• a description of the feed: This RSS feed contains news feeds for eZ Publish and eZ Components.

• a published date (called pubDate in RSS2) for the feed: Wed, 05 Mar 2008 14:28:45 +0000

• an author (called managerEditor in RSS2): nospam@ez.no (Derick) (this is the recommended way to specify an author in RSS2, with an email address and the name of the person in paranthesis)

• a link to our website: http://ez.no/

• the news items (a short story about each product release)

A news item can be defined by these elements (example for one news item):

• the title of the news item: eZ Components 2007.1 released

• a short description of the news item: The new release of eZ Components include Workflow, Authentication...

• a published date (called pubDate in RSS2) for the news item: Mon, 02 Jul 2007 11:36:45 +0000

• an author of the news item: nospam@ez.no (Derick) (this is the recommended way to specify an author in RSS2, with an email address and the name of the person in paranthesis)

• a link to the detailed article on our website: http://ezcomponents.org/resources/news/news-2007-07-02 (this will show in most aggregator programs as a Complete story link)

Step 1. Create a feed object

A feed object can be created by calling the constructor with the optional feed type (atom, rss1 or rss2). In our case we create an generic feed:

1. <?php
2. // use eZ Components autoload mechanism
3. require_once 'tutorial_autoload.php';
5. $feed = new ezcFeed();
?>

The type of the resulting XML feed document will be specified in Step 5. Generate the XML feed.

Step 2. Add feed elements

We add the title, description and author to the feed:

1. <?php
2. $feed->title = 'eZ news feed';
3. $feed->description = 'This RSS feed contains news feeds for eZ Publish and eZ Components';
4. $feed->published = 'Wed, 05 Mar 2008 14:28:45 +0000';
?>

Because some feed types support multiple link and author elements, multiple elements of this type can be added to a feed (although this is not fully supported by RSS2 Specifications or by aggregator programs).

The way to add an element which can appear multiple times, or an element which supports attributes, is to call the method add() from ezcFeed or ezcFeedElement classes. The attributes of the element are set as simple properties (the way $feed->title is set).

So to add a author element to our feed, we will do:

1. <?php
2. $author = $feed->add( 'author' );
3. $author->name = 'Derick';
4. $author->email = 'nospam@ez.no';
?>

In the above example. $author is an object of type ezcFeedPersonElement. Other properties can be set on it (uri) which are mainly used for ATOM feeds. When generating an RSS2 feed, the generated XML element will look like this (from the values added to the $author object above):

In ATOM it will look like this:

To add a link element to our feed, we will do:

1. <?php
2. $link = $feed->add( 'link' );
3. $link->href = 'http://ez.no/';
?>

In the above example. $link is an object of type ezcFeedLinkElement. Other properties can be set on it (title, rel, hreflang, type, length) which are mainly used for ATOM feeds.

Step 3. Add an item

A feed item is an element which can appear multiple times, so it is added via the method add() of ezcFeed:

1. <?php
2. $item = $feed->add( 'item' );
?>

Next we add the title, description and author elements to the news item:

1. <?php
2. $item->title = 'eZ Components 2007.1 released';
3. $item->description = 'The new release of eZ Components include Workflow, Authentication...';
4. $item->published = 'Mon, 02 Jul 2007 11:36:45 +0000';
?>

We add the link and author elements to the news item in the same way as for the feed:

1. <?php
2. $author = $item->add( 'author' );
3. $author->name = 'Derick';
4. $author->email = 'nospam@ez.no';
6. $link = $item->add( 'link' );
7. $link->href = 'http://ezcomponents.org/resources/news/news-2007-07-02';
?>

Step 4. Add more items

To add more news items to our feed, we repeat the step 3 as many times as needed.

Step 5. Generate the XML feed

To create the XML feed from the $feed object, we call the generate() method of ezcFeed:

1. <?php
2. $xml = $feed->generate( 'rss2' );
?>

After running this line, $xml will contain the XML string of the feed (in case no exceptions were thrown due to required elements not being present).

This is the string from $xml with 3 news items:

Some elements were added automatically, namely lastBuildDate (current system time at generation time), generator (eZ Components Feed along with the version of the Feed component (dev) and a link to this tutorial) and docs (http://www.rssboard.org/rss-specification - a link to the RSS2 Specifications).

If you want to generate ATOM and RSS1 feed documents at this step, you can call generate() with atom and rss1 respectively as arguments. As some elements are required for ATOM and RSS1, you might receive an exception. In this case add the required elements and call generate() again.

Step 6. Save the XML feed to a file

The generated XML feed needs to be saved in a file in order to be made accessible to users of your website:

1. <?php
2. file_put_contents( 'feeds/news.xml', $xml );
?>

Assuming that our host is ez.no, this will be the location of our newly created XML feed: http://ez.no/feeds/news.xml.

You can also output the XML directly, while setting the HTTP Content-Type header:

1. <?php
2. $xml = $feed->generate( 'rss2' );
3. header( 'Content-Type: ' . $feed->getContentType() . '; charset=utf-8' );
4. echo $xml;
?>

Assuming that this script is kept in http://ez.no/feeds/news.php, when opening this URL in a web browser, the XML will be output with the content-type application/rss+xml. If the browser is configured properly to handle this content-type, it will open the feed aggregator software program, otherwise it will ask the user which application to use for that content-type.

Step 7. Feed validation

Use a feed validator to validate your newly created feed. Some warnings can appear, but unless the feed is not validated, it should be parseable by most applications and aggregator programs.

Step 8. Make the XML feed accessible

There are some methods to let the user know that a website provides an XML feed, so that the user can save the feed link in his feed aggregator.

Automatic feed discovery

In the HTML source of every page add this line for RSS1 or RSS2 feeds:

Or this line for ATOM feeds:

In modern browsers the user will be informed (usually via a small icon like in one corner of the browser or in the address bar) that the current page has a web feed. If the user clicks on this icon his feed aggregator client will start and save the link to the feed in its database (if the user's system has a feed aggregator client and is configured to handle application/rss+xml and application/atom+xml content with the aggregator).

Multiple feeds can be added to the same page (for example you can provide ATOM and RSS2 feeds). Note: some browsers might not recognize the non-standard application/rss+xml type and select the ATOM feed by default.

The title attribute of the link HTML tag can be used to differentiate between multiple feeds (for example News, Latest offers, etc).

Link to the feed document

In the HTML source of every page (usually in the header and/or footer) add this line for RSS1 or RSS2 feeds:

Or this line for ATOM feeds:

The user can drag this link to his feed aggregator, where it will be added to the aggregator's database of feeds.

It is customary to add the feed icon next to a feed link, so that the user finds the feed link easier on the page. See this Mozilla page for more information about the feed icon.

Feed creator example

In the sub-directory Feed/docs/examples there is a feed_creator application which can be used to create simple XML feeds from minimal text files.

The structure of the text files accepted by this application is:

An example of an input text file:

The feed_creator application will read an input file with the above structure and output an XML feed of the chosen type (rss1, rss2 or atom). An XML file will also be written in the same directory as the input file, with the name of the input file plus the .xml extension.

Special characters need to be encoded already in the input text file (eg. if the title contains &, it should appear as & in the input text file).

Example of usage (current directory is the feed_creator directory):

After running this command, the file data/news.xml will be created, containing an RSS2 feed with the values read from data/news.txt:

See the section Step 8. Make the XML feed accessible for details on how to provide access to the generated XML feed.

How to create an iTunes podcast

A podcast is a collection of media files (called episodes) distributed over the Internet using XML feeds. The podcast doesn't contain the media file, but it contains links to these media files, plus information about the files (meta-information) like creator, duration, category, copyright information, etc.

The Feed component supports creating and parsing feeds which define podcasts.

This part of the tutorial will show you step by step how to create an RSS2 podcast with iTunes elements. The iTunes media player supports RSS2 feeds, so creating ATOM or RSS1 podcasts for iTunes is not recommended (although possible).

The information which we want to show in the podcast is:

• the title of the feed: Flight of the RC plane

• a description of the feed. This will also be used if we don't declare the summary iTunes element. The contents of this element are shown in iTunes in a separate window that appears when the "circled i" in the Description column is clicked: A podcast for fans of remote-control planes, with information about planes, competitions, tutorials and tips

• an author (called managerEditor in RSS2): editor@rcplanes.example.com (Derick) (this is the recommended way to specify an author in RSS2, with an email address and the name of the person in paranthesis)

• a link to our website: http://rcplanes.example.com/

• the episodes or items (information about each episode, a link to the media file associated with the episode and iTunes meta-information for the media files)

• iTunes elements needed to be able to submit our podcast to iTunes.

iTunes elements for the whole feed:

• one or more category elements (from the page iTunes categories). Our podcast could be for example in the category Technology, sub-category Gadgets

• one or more keywords, separated by commas: RC planes,gadgets,flying

• an image for our podcast. iTunes recommends an image of at least 500x500 pixels: http://rcplanes.example.com/images/rc_plane_big.jpg

• a subtitle for our podcast. This is shown in the Description column in iTunes. Should be a very short description: Competitions, tutorials and tips for remote-control planes.

• explicit status (some of our RC pilots are known to curse a lot): yes (other values are no and clean, with no being the default)

An episode can be defined by these elements (example for one episode):

• the title of the episode: Flying an RC plane indoors

• a short description of the episode: In this episode, Derick talks about how to fly an RC plane in a big hall, around people working and throwing stuff at the plane.

• an author of the episode: derick@rcplanes.example.com (Derick) (this is the recommended way to specify an author in RSS2, with an email address and the name of the person in paranthesis)

• a link to the detailed article on our website: http://rcplanes.example.com/articles/fly-an-rc-plane-indoors.html

• an enclosure, which is a link to a media file: http://rcplanes.example.com/media/003-flying-indoors.mp3. Other information can also be provided as attributes for the enclosure, namely length in bytes and type (audio/x-mp3 in our case)

• the date and time of the episode, or published (called pubDate in RSS2). The iTunes program uses this timestamp to download the latest episode automatically: Fri, 04 Jan 2008 11:18:34 +0100

In addition, these iTunes elements are added for each episode:

• duration of the episode: 29:20 (29 minutes 20 seconds). Other ways to specify the duration are S, M:SS, MM:SS, H:MM:SS or HH:MM:SS (H = hours, M = minutes, S = seconds).

• one or more keywords, separated by commas: RC planes,office,flying,enemies

See the section How to create a feed for detailed steps. This part of the tutorial will concentrate on how to add the iTunes information to the feed.

Step 1. Create an RSS2 feed

We start with creating an RSS2 feed object, which we fill with title, description, author and link elements:

1. <?php
2. // use eZ Components autoload mechanism
3. require_once 'tutorial_autoload.php';
5. $feed = new ezcFeed( 'rss2' );
7. $feed->title = 'Flight of the RC plane';
8. $feed->description = 'A podcast for fans of remote-control planes, with information about planes, competitions, tutorials and tips';
10. $author = $feed->add( 'author' );
11. $author->name = 'Derick';
12. $author->email = 'editor@rcplanes.example.com';
14. $link = $feed->add( 'link' );
15. $link->href = 'http://rcplanes.examples.com/';
?>

Step 2. Add iTunes feed elements

The iTunes elements will be contained in an iTunes module. A module is added to an ezcFeed or ezcFeedItem object using the method addModule(). A module is an object of class ezcFeedModule.

Next we will add category, keywords, image, subtitle and explicit iTunes elements to our $feed object:

1. <?php
2. $iTunes = $feed->addModule( 'iTunes' );
4. $iTunes->keywords = 'RC planes,gadgets,flying';
5. $iTunes->explicit = 'yes';
6. $iTunes->subtitle = 'Competitions, tutorials and tips for remote-control planes';
8. // add an image for the podcast
9. $image = $iTunes->add( 'image' );
10. $image->link = 'http://rcplanes.example.com/images/rc_plane_big.jpg';
12. // add the podcast in the category Technology->Gadgets
13. $category = $iTunes->add( 'category' );
14. $category->term = 'Technology';
15. $subCategory = $category->add( 'category' );
16. $subCategory->term = 'Gadgets';
?>

See the iTunes categories page for a list of the iTunes categories you can add a podcast to. Note: some category names contain & which should be encoded as & (eg. Society & Culture).

Step 3. Add an item

Next we will add an episode (item) to our $feed object, and we will add the title, description, author and link elements to it:

1. <?php
2. $item = $feed->add( 'item' );
4. $item->title = 'Flying an RC plane indoors';
5. $item->description = 'In this episode, Derick talks about how to fly an RC plane in a big hall, around people working and throwing stuff at the plane';
6. $item->published = 'Fri, 04 Jan 2008 11:18:34 +0100';
8. $author = $item->add( 'author' );
9. $author->name = 'Derick';
10. $author->email = 'derick@rcplanes.example.com';
12. $link = $item->add( 'link' );
13. $link->href = 'http://rcplanes.example.com/articles/fly-an-rc-plane-indoors.html';
15. $enclosure = $item->add( 'enclosure' );
16. $enclosure->url = 'http://rcplanes.example.com/media/003-flying-indoors.mp3';
17. $enclosure->length = 49099054; // bytes
18. $enclosure->type = 'audio/x-mp3';
?>

Step 4. Add iTunes item elements

We will add the iTunes elements duration and keywords to our $item object from the previous step:

1. <?php
2. $iTunes = $item->addModule( 'iTunes' );
4. $iTunes->duration = '29:20';
5. $iTunes->keywords = 'RC planes,office,flying,enemies';
?>

Step 5. Add more items

To add more episodes to our podcast, we repeat the steps 3 and 4 as many times as needed.

Step 6. Generate the XML feed

Follow these steps from the previous tutorial How to create a feed:

• Step 5. Generate the XML feed

• Step 6. Save the XML feed to a file

• Step 7. Feed validation

• Step 8. Make the XML feed accessible

In the end, our podcast will look like this (with 3 episodes added):

Step 7. Submit the podcast to the iTunes Store

Follow the steps on the section Submitting Your Podcast to the iTunes Store from the iTunes Specifications.

The iTunes Specifications contains other useful information you might need when you are creating podcasts.

How to parse an XML feed

An XML feed can be stored in a file, at an URL or in a string variable. By using the methods parse() (for files and URLs) or parseContent() (for string variables), an ezcFeed object can be created from an XML feed.

This part of the tutorial will show you step by step how to parse an XML feed, read its elements, iterate over the items in the feed and read the items' elements.

Step 1. Parse an XML feed

If the XML feed is stored in a file or URL, use the static method parse() from ezcFeed to parse the feed and create an ezcFeed object out of it:

1. <?php
2. // use eZ Components autoload mechanism
3. require_once 'tutorial_autoload.php';
5. $feed = ezcFeed::parse( 'http://ezcomponents.org/feed/news.xml' ); // URL
6. $feed = ezcFeed::parse( '/tmp/news.xml' ); // local file
?>

If the XML feed is protected with HTTP authentication (username and password required in order to access it), provide the username and password in the URL:

1. <?php
2. // use eZ Components autoload mechanism
3. require_once 'tutorial_autoload.php';
5. $feed = ezcFeed::parse( 'http://username:password@ezcomponents.org/feed/news.xml' );
?>

If trying to parse an XML document protected with HTTP authentication without providing a valid username and password, an ezcFeedParseErrorException will be thrown.

If the XML feed is stored in a string variable, use the static method parseContent() from ezcFeed to parse the feed and create an ezcFeed object out of it:

1. <?php
2. // use eZ Components autoload mechanism
3. require_once 'tutorial_autoload.php';
5. $feed = ezcFeed::parseContent( $xml ); // $xml is a string
?>

These exceptions can be thrown while parsing a feed:

• ezcBaseFileNotFoundException - if the feed URL or file is not found

• ezcFeedParseErrorException - if the XML content is broken, or not a feed, or unsupported feed type, or if RSS1 and RSS2 feeds are missing the <channel> element

Step 2. Read the feed elements

At step 1 we created an ezcFeed object by parsing an XML feed. Next we will read the elements from the feed.

Depending on the feed type, certain elements are present while others are not. The feed type can be retrieved via the method getFeedType() from ezcFeed:

1. <?php
2. $feedType = $feed->getFeedType();
?>

This will return rss1, rss2 or atom.

It is always a good idea to read only those elements which are present in $feed. To test if an element is present, call isset() on it:

1. <?php
2. if ( isset( $feed->title ) )
3. {
4.     $title = $feed->title->__toString();
5. }
?>

Another way to write this is (assuming that a missing title can be considered null):

1. <?php
2. $title = isset( $feed->title ) ? $feed->title->__toString() : null;
?>

Depending on your application, you might need only some elements, let's say title, description, author and link. So to read those elements you will use:

1. <?php
2. $title = isset( $feed->title ) ? $feed->title->__toString() : null;
3. $description = isset( $feed->description ) ? $feed->description->__toString() : null;
5. if ( isset( $feed->author ) )
6. {
7.     $author = isset( $feed->author->name ) ? $feed->author->name : null;
8.     // RSS2 feeds usually have the author in this format: email_address (author_name)
9.     // the $author string can be parsed to extract the email and name.
10.     //
11.     // ATOM feeds contain the author's email in a separate element: $feed->author->email.
12.     // and in addition they have the uri element for authors: $feed->author->uri
13. }
15. $links = array();
16. if ( isset( $feed->link ) )
17. {
18.     foreach ( $feed->link as $link )
19.     {
20.         $links[] = $link->href;
21.     }
22. }
?>

Because link can appear multiple times, we had to resort to this long code to get the links out of the feed. The $links array will be empty if no links are in the XML feed, or will contain all the links that appear on the feed-level.

Step 3. Iterate over the feed items

A feed can contain zero or more item elements.

Let's say we want to extract the title, description, published, author and link of all items. This is how we will do it:

1. <?php
2. $items = array();
3. foreach ( $feed->item as $item )
4. {
5.     $title = isset( $item->title ) ? $item->title->__toString() : null;
6.     $description = isset( $item->description ) ? $item->description->__toString() : null;
7.     $published = isset( $item->published ) ? $item->published->date->format( 'c' ) : null;
9.     if ( isset( $item->author ) )
10.     {
11.         $author = isset( $item->author->name ) ? $item->author->name : null;
12.         // RSS2 feeds usually have the author in this format: email_address (author_name)
13.         // the $author string can be parsed to extract the email and name
14.         //
15.         // ATOM feeds contain the author's email in a separate element: $item->author->email.
16.         // and in addition they have the uri element for authors: $item->author->uri
17.     }
19.     $links = array();
20.     if ( isset( $item->link ) )
21.     {
22.         foreach ( $item->link as $link )
23.         {
24.             $links[] = $link->href;
25.         }
26.     }
28.     $items[] = array( 'title' => $title,
29.                       'description' => $description,
30.                       'author' => $author,
31.                       'links' => $links );
32. }
?>

The published element is an ezcFeedDateElement object encapsulating a DateTime object, so we return the date as a string with format( 'c' ). Other formats can be used also, see the documentation for date_format().

How to parse an iTunes podcast

See the section How to parse an XML feed for detailed steps. This part of the tutorial will concentrate on how to fetch the iTunes information from an RSS2 feed.

Step 1. Parse an XML feed

If the XML feed is stored in a file or URL, use the static method parse() from ezcFeed to parse the feed and create an ezcFeed object out of it:

1. <?php
2. // use eZ Components autoload mechanism
3. require_once 'tutorial_autoload.php';
5. $feed = ezcFeed::parse( 'http://rcplanes.example.com/feed/podcast.xml' );
6. $feed = ezcFeed::parse( '/tmp/podcast.xml' ); // local file
?>

If the XML feed is protected with HTTP authentication (username and password required in order to access it), provide the username and password in the URL:

1. <?php
2. // use eZ Components autoload mechanism
3. require_once 'tutorial_autoload.php';
5. $feed = ezcFeed::parse( 'http://username:password@rcplanes.example.com/feed/podcast.xml' );
?>

If trying to parse an XML document protected with HTTP authentication without providing a valid username and password, an ezcFeedParseErrorException will be thrown.

If the XML feed is stored in a string variable, use the static method parseContent() from ezcFeed to parse the feed and create an ezcFeed object out of it:

1. <?php
2. // use eZ Components autoload mechanism
3. require_once 'tutorial_autoload.php';
5. $feed = ezcFeed::parseContent( $xml ); // $xml is a string
?>

Step 2. Read the feed elements

Depending on the feed type, certain elements are present while others are not. The feed type can be retrieved via the method getFeedType() from ezcFeed:

1. <?php
2. $feedType = $feed->getFeedType();
?>

This will return rss1, rss2 or atom.

Depending on your application, you might need only some elements, let's say title, description, author and link. So to read those elements you will use:

1. <?php
2. $title = isset( $feed->title ) ? $feed->title->__toString() : null;
3. $description = isset( $feed->description ) ? $feed->description->__toString() : null;
5. if ( isset( $feed->author ) )
6. {
7.     $author = isset( $feed->author->name ) ? $feed->author->name : null;
8.     // RSS2 feeds usually have the author in this format: email_address (author_name)
9.     // the $author string can be parsed to extract the email and name
10.     //
11.     // ATOM feeds contain the author's email in a separate element: $feed->author->email.
12.     // and in addition they have the uri element for authors: $feed->author->uri
13. }
15. $links = array();
16. if ( isset( $feed->link ) )
17. {
18.     foreach ( $feed->link as $link )
19.     {
20.         $links[] = $link->href;
21.     }
22. }
?>

Step 3. Read the iTunes feed elements

Before reading iTunes elements from the feed, we need to make sure that the feed has the iTunes module. We use the method hasModule() from ezcFeed or ezcFeedItem:

1. <?php
2. if ( $feed->hasModule( 'iTunes' ) )
3. {
4.     // process the iTunes module
5. }
?>

We can also call the isset() method to check if the iTunes module is present:

1. <?php
2. if ( isset( $feed->iTunes ) )
3. {
4.     // process the iTunes module
5. }
?>

This is how we fetch information from the iTunes module. Let's say we want to fetch the keywords, subtitle, image and category elements:

1. <?php
2. if ( isset( $feed->iTunes ) )
3. {
4.     $iTunes = $feed->iTunes;
5.     $keywords = isset( $iTunes->keywords ) ? $iTunes->keywords->__toString() : null;
6.     $subtitle = isset( $iTunes->subtitle ) ? $iTunes->subtitle->__toString() : null;
7.     $image = isset( $iTunes->image ) ? $iTunes->image->__toString() : null;
9.     $categories = array();
10.     if ( isset( $iTunes->category ) )
11.     {
12.         foreach ( $iTunes->category as $category )
13.         {
14.             $cat = array( 'term' => $category->term );
15.             if ( isset( $category->category ) )
16.             {
17.                 $cat['subCategory'] = $category->category->term;
18.             }
20.             $categories[] = $cat;
21.         }
22.     }
23. }
?>

In iTunes, category is an element which can have sub-categories. The code above reads the category values (from the text attribute) and the sub-category (if any) from each category. The $categories array can look like this:

if the iTunes elements appeared like this in the XML feed:

Step 4. Iterate over the feed items

Let's say we want to extract the title, description, published, author and link of all items. This is how we will do it:

1. <?php
2. $items = array();
3. foreach ( $feed->item as $item )
4. {
5.     $title = isset( $item->title ) ? $item->title->__toString() : null;
6.     $description = isset( $item->description ) ? $item->description->__toString() : null;
7.     $published = isset( $item->published ) ? $item->published->date->format( 'c' ) : null;
9.     if ( isset( $item->author ) )
10.     {
11.         $author = isset( $item->author->name ) ? $item->author->name : null;
12.         // RSS2 feeds usually have the author in this format: email_address (author_name)
13.         // the $author string can be parsed to extract the email and name
14.         //
15.         // ATOM feeds contain the author's email in a separate element: $item->author->email.
16.         // and in addition they have the uri element for authors: $item->author->uri
17.     }
19.     $links = array();
20.     if ( isset( $item->link ) )
21.     {
22.         foreach ( $item->link as $link )
23.         {
24.             $links[] = $link->__toString();
25.         }
26.     }
28.     $media = array();
29.     if ( isset( $item->enclosure ) )
30.     {
31.         $enclosure = $item->enclosure[0];
33.         $media = array(
34.            'url' => isset( $enclosure->url ) ? $enclosure->url : null,
35.            'length' => isset( $enclosure->length ) ? $enclosure->length : null,
36.            'type' => isset( $enclosure->type ) ? $enclosure->type : null
37.            );
38.     }
40.     $items[] = array( 'title' => $title,
41.                       'description' => $description,
42.                       'author' => $author,
43.                       'links' => $links,
44.                       'media' => $media );
45. }
?>

After running the code, the $media array will contain the url, length and type of the media file specified in the feed item. The $media array is added to the $items array to be processed later by the application.

Step 5. Read the iTunes item elements

Let's say we want to fetch the duration of the iTunes module inside an item. The code from the previous section is altered as follows:

1. <?php
2. // ...
3.     $media = array();
4.     if ( isset( $item->enclosure ) )
5.     {
6.         $enclosure = $item->enclosure[0];
8.         $media = array(
9.            'url' => isset( $enclosure->url ) ? $enclosure->url : null,
10.            'length' => isset( $enclosure->length ) ? $enclosure->length : null,
11.            'type' => isset( $enclosure->type ) ? $enclosure->type : null
12.            );
14.         if ( isset( $item->iTunes ) )
15.         {
16.             $iTunes = $item->iTunes;
17.             $media['duration'] = isset( $iTunes->duration ) ? $iTunes->duration : null;
18.         }
19.     }
20. // ...
?>

After running the code, the $media array will contain the url, length and type of the media file specified in the feed item, and the duration of the media file taken from the iTunes module (if available).

Best practices

This section lists some useful tips for handling feed documents.

Universal feed generator

In order to generate all 3 feed types (ATOM, RSS1, RSS2) from the same ezcFeed data, these elements must be added to an ezcFeed object:

• author

• description

• id

• at least one item with all required elements

• link

• title

• updated

And these elements must be added to an ezcFeedEntryElement object:

• author

• description

• id

• link

• title

• updated

This is a minimal script to be able to generate all 3 feed types from the same ezcFeed data:

1. <?php
2. // use eZ Components autoload mechanism
3. require_once 'tutorial_autoload.php';
5. $feed = new ezcFeed();
7. $author = $feed->add( 'author' );
8. $author->name = "Indiana Jones";
9. $author->email = "indy@example.com";
11. $feed->description = "This feed shows Indiana Jones movie releases";
12. $feed->id = "http://indy.example.com/";
14. $link = $feed->add( 'link' );
15. $link->href = "http://indy.example.com/";
17. $feed->title = "Indiana Jones movie releases";
18. $feed->updated = time();
20. // add a feed item
21. $item = $feed->add( 'item' );
23. $author = $item->add( 'author' );
24. $author->name = "Indiana Jones";
25. $author->email = "indy@example.com";
27. $item->description = "Indy meets ****** and has a hell of an adventure";
28. $item->id = "http://indy.example.com/4";
30. $link = $item->add( 'link' );
31. $link->href = "http://indy.example.com/4";
33. $item->title = "Indiana Jones and the Kingdom of the Crystal Skull";
34. $item->updated = time();
36. $atom = $feed->generate( 'atom' );
37. $rss1 = $feed->generate( 'rss1' );
38. $rss2 = $feed->generate( 'rss2' );
?>

Self link

A feed validator application will usually recommend that a feed contains a link to itself, in other words the URL of the feed should be included inside the feed.

To add this information to a feed, use the following section.

ATOM

Add a link element with the attribute rel=self (this is required):

RSS1

Use the about attribute, accessed as id (this is required):

RSS2

Most feed validator applications will recommend to include in an RSS2 feed a link to the location of the feed. For example, if the XML document containing the RSS2 feed is located at 'http://example.com/rss/', then this URL should be contained in the feed itself in an atom:link element, since RSS2 does not offer a mechanism to specify self-links.

Use the id element of a feed to add this self-link:

This will be rendered in XML as:

Media type

ATOM

All ATOM feeds must be identified with the application/atom+xml media type. Use the getContentType() method after calling generate( 'atom' ) on an ezcFeed object to get this string, or use ezcFeedAtom::CONTENT_TYPE.

RSS1

All RSS1 feeds should be identified with the application/rss+xml media type (although it is not a standard yet). Use the getContentType() method after calling generate( 'rss1' ) on an ezcFeed object to get this string, or use ezcFeedRss1::CONTENT_TYPE.

RSS2

All RSS2 feeds should be identified with the application/rss+xml media type (although it is not a standard yet). Use the getContentType() method after calling generate( 'rss2' ) on an ezcFeed object to get this string, or use ezcFeedRss2::CONTENT_TYPE.

Extending the Feed component

Register a new feed type

A new feed type can be defined by creating a class which extends the class ezcFeedProcessor and implements the interface ezcFeedParser. The new class needs to be added to the supported feed types list by calling the ezcFeed::registerFeed() function.

Example of new feed type:

1. <?php
2. class myOpmlHandler extends ezcFeedProcessor implements ezcFeedParser
3. {
4.     const CONTENT_TYPE = 'text/x-opml';
5.     const FEED_TYPE = 'opml';
7.     public function __construct( ezcFeed $container )
8.     {
9.         $this->feedContainer = $container;
10.         $this->feedType = self::FEED_TYPE;
11.         $this->contentType = self::CONTENT_TYPE;
12.     }
14.     public function generate()
15.     {
16.         // write implementation here
18.         // should return XML as a string based on the feed elements from
19.         // $this->feedContainer which are accessed as $this->element_name
20.         // (example $this->title)
21.     }
23.     public static function canParse( DOMDocument $xml )
24.     {
25.         // write implementation here
27.         // should return true if this class can parse the $xml DOMDocument received
28.         // and false otherwise
29.     }
31.     public function parse( DOMDocument $xml )
32.     {
33.         // write implementation here
35.         $feed = new ezcFeed();
37.         // parse $xml and fill $feed with properties fetched from $xml
39.         return $feed;
40.     }
41. }
?>

Example of how to use the feed type above:

1. <?php
2. // use eZ Components autoload mechanism
3. require_once 'tutorial_autoload.php';
5. ezcFeed::registerFeed( 'opml', 'myOpmlHandler' );
6. $feed = new ezcFeed();
7. // fill $feed with OPML properties
9. $xml = $feed->generate( 'opml' );
?>

Register a new module

A new module can be defined by creating a class which extends the class ezcFeedModule. The new class needs to be added to the supported modules list by calling the ezcFeed::registerModule() function.

Example of a new module type:

1. <?php
2. class mySlashHandler extends ezcFeedModule
3. {
4.     public function __construct( $level = 'feed' )
5.     {
6.         parent::__construct( $level );
7.     }
9.     public function generate( DOMDocument $xml, DOMNode $root )
10.     {
11.         // write implementation here
13.         // should fill $root with values from $this
14.     }
16.     public function parse( $name, DOMElement $node )
17.     {
18.         // write implementation here
20.         // should parse $node and add a new ezcFeedElement to $this with name $name
21.     }
24.     public function isElementAllowed( $name )
25.     {
26.         // return true if the element $name is allowed in this module at level $this->level,
27.         // and false otherwise
28.     }
30.     public function add( $name )
31.     {
32.         // add the element $name to this module at level $this->level (feed-level or item-level)
33.     }
35.     public static function getModuleName()
36.     {
37.         return 'Slash';
38.     }
40.     public static function getNamespace()
41.     {
42.         return 'http://purl.org/rss/1.0/modules/slash/';
43.     }
45.     public static function getNamespacePrefix()
46.     {
47.         return 'slash';
48.     }
49. }
?>

Example of how to use the module above:

1. <?php
2. // use eZ Components autoload mechanism
3. require_once 'tutorial_autoload.php';
5. ezcFeed::registerModule( 'Slash', 'mySlashHandler', 'slash');
7. $feed = new ezcFeed();
8. $item = $feed->add( 'item' );
9. $slash = $item->addModule( 'Slash' );
10. // add properties for the Slash module to $slash
12. $xml = $feed->generate( 'rss2' ); // or the feed type which is needed
?>

Specifications and RFCs

For a list of supported RFCs and specifications of the feed types and modules, please see the specifications page.