Path

ez components / documentation / api reference / 2008.1alpha1 / feed


eZ Components 2008.1alpha1

Feed

[ Tutorial ] [ Specifications ] [ Class tree ] [ Element index ] [ ChangeLog ] [ Credits ]

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:

<?xml version="1.0"?>
<rss version="2.0">
<channel>
  <title>Liftoff News</title>
  <link>http://liftoff.msfc.nasa.gov/</link>
  <description>Liftoff to Space Exploration.</description>
  <language>en-us</language>
  <pubDate>Tue, 10 Jun 2003 04:00:00 GMT</pubDate>
  <webMaster>webmaster@example.com</webMaster>
  <item>
	<title>The Engine That Does More</title>
	<link>http://liftoff.msfc.nasa.gov/news/2003/news-VASIMR.asp</link>
	<description>Before man travels to Mars, NASA hopes to design new engines
	that will let us fly through the Solar System more quickly. The proposed
	VASIMR engine would do that.</description>
	<pubDate>Tue, 27 May 2003 08:37:32 GMT</pubDate>
	<guid>http://liftoff.msfc.nasa.gov/2003/05/27.html#item571</guid>
  </item>
  <item>
	<title>Astronauts' Dirty Laundry</title>
	<link>http://liftoff.msfc.nasa.gov/news/2003/news-laundry.asp</link>
	<description>Compared to earlier spacecraft, the International Space Station
	has many luxuries, but laundry facilities are not one of them. Instead,
	astronauts have other options.</description>
	<pubDate>Tue, 20 May 2003 08:56:02 GMT</pubDate>
	<guid>http://liftoff.msfc.nasa.gov/2003/05/20.html#item570</guid>
  </item>
</channel>
</rss>

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:

<?xml version="1.0" encoding="UTF-8"?>
<rss xmlns:itunes="http://www.itunes.com/dtds/podcast-1.0.dtd" version="2.0">
<channel>
  <title>All About Everything</title>
  <link>http://www.example.com/podcasts/everything/index.html</link>
  <description>All About Everything is a show about everything. Each week we dive
  into any subject known to man and talk about it as much as we can. Look for our
  Podcast in the iTunes Music Store</description>
  <itunes:subtitle>A show about everything</itunes:subtitle>
  <itunes:author>John Doe</itunes:author>
  <itunes:summary>All About Everything is a show about everything. Each week we dive
  into any subject known to man and talk about it as much as we can. Look for our
  Podcast in the iTunes Music Store</itunes:summary>
  <itunes:image href="http://example.com/podcasts/everything/AllAboutEverything.jpg" />
  <itunes:category text="Technology">
    <itunes:category text="Gadgets"/>
  </itunes:category>
  <itunes:category text="TV &amp; Film"/>

  <item>
    <title>Shake Shake Shake Your Spices</title>
    <enclosure url="http://example.com/podcasts/everything/AllAboutEverythingEpisode3.m4a" length="8727310" type="audio/x-m4a" />
    <guid>http://example.com/podcasts/archive/aae20050615.m4a</guid>
    <pubDate>Wed, 15 Jun 2005 19:00:00 GMT</pubDate>
    <itunes:author>John Doe</itunes:author>
    <itunes:subtitle>A short primer on table spices</itunes:subtitle>
    <itunes:summary>This week we talk about salt and pepper shakers, comparing and
	contrasting pour rates, construction materials, and overall aesthetics. Come
	and join the party!</itunes:summary>
    <itunes:duration>7:04</itunes:duration>
    <itunes:keywords>salt, pepper, shaker, exciting</itunes:keywords>
  </item>
 
  <item>
    <title>Red, Whine, &amp; Blue</title>
    <enclosure url="http://example.com/podcasts/everything/AllAboutEverythingEpisode1.mp3" length="4989537" type="audio/mpeg" />
    <guid>http://example.com/podcasts/archive/aae20050601.mp3</guid>
    <pubDate>Wed, 1 Jun 2005 19:00:00 GMT</pubDate>
    <itunes:author>Various</itunes:author>
    <itunes:subtitle>Red + Blue != Purple</itunes:subtitle>
    <itunes:summary>This week we talk about surviving in a Red state if you are a
	Blue person. Or vice versa.</itunes:summary>
    <itunes:duration>3:59</itunes:duration>
    <itunes:keywords>politics, red, blue, state</itunes:keywords>
  </item>
</channel>
</rss>

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
Defines an element in a feed object.
ezcFeedItem
Defines a feed item in a feed object.
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:

A new processor can be defined by creating a class which extends the class ezcFeedProcessor and implements the interface ezcFeedParser, and adding it to the ezcFeed::$supportedFeedTypes array.

Supported feed modules

The following modules are supported by the Feed component:

A new module can be defined by creating a class which extends the class ezcFeedModule, and adding it to the ezcFeed::$supportedModules and ezcFeed::$supportedModulesPrefixes arrays.

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 required feed type (atom, rss1 or rss2). In our case we create an RSS2 feed:

$feed = new ezcFeed( 'rss2' );

Step 2. Add feed elements

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

$feed->title = 'eZ news feed';
$feed->description = 'This RSS feed contains news feeds for eZ Publish and eZ Components';
$feed->published = 'Wed, 05 Mar 2008 14:28:45 +0000';
$feed->author = 'nospam@ez.no (Derick)';

Because some feed types support multiple link elements, multiple link elements 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 / ezcFeedItem. The value of the element is set via the method set() from ezcFeedElement / ezcFeedItem, and the attributes of the element are set as simple properties (the way $feed->title is set).

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

$link = $feed->add( 'link' );
$link->set( 'http://ez.no' );

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:

$item = $feed->add( 'item' );

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

$item->title = 'eZ Components 2007.1 released';
$item->description = 'The new release of eZ Components include Workflow, Authentication...';
$item->published = 'Mon, 02 Jul 2007 11:36:45 +0000';
$item->author = 'nospam@ez.no (Derick)';

We add the link element to the news item in the same way as for the feed:

$link = $item->add( 'link' );
$link->set( '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:

$xml = $feed->generate();

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:

<?xml version="1.0" encoding="utf-8"?>
<rss version="2.0">
  <channel>
    <title>eZ news feed</title>
    <link>http://ez.no</link>
    <description>This RSS feed contains news feeds for eZ Publish and eZ Components.</description>
    <managingEditor>nospam@ez.no (Derick)</managingEditor>
    <pubDate>Wed, 05 Mar 2008 14:28:45 +0000</pubDate>
    <lastBuildDate>Tue, 11 Mar 2008 09:46:43 +0000</lastBuildDate>
    <generator>eZ Components Feed dev (http://ezcomponents.org/docs/tutorials/Feed)</generator>
    <docs>http://www.rssboard.org/rss-specification</docs>
    <item>
      <title>eZ Components 2007.1 released</title>
      <link>http://ezcomponents.org/resources/news/news-2007-07-02</link>
      <description>The new release of eZ Components include Workflow, Authentication...</description>
      <author>nospam@ez.no (Derick)</author>
      <guid isPermaLink="true">http://ezcomponents.org/resources/news/news-2007-07-02</guid>
      <pubDate>Mon, 02 Jul 2007 11:36:45 +0000</pubDate>
    </item>
    <item>
      <title>eZ Publish 4.0 released</title>
      <link>http://ez.no/company/news/first_stable_ez_publish_4_0_release_for_php_5</link>
      <description>The new release of eZ Publish is based on PHP 5....</description>
      <author>nospam@ez.no (Ole)</author>
      <guid isPermaLink="true">http://ez.no/company/news/first_stable_ez_publish_4_0_release_for_php_5</guid>
      <pubDate>Tue, 03 Jul 2007 16:59:00 +0000</pubDate>
    </item>
    <item>
      <title>eZ Find 1.0 released</title>
      <link>http://ez.no/ezfind/news/ez_find_1_0_2_for_ez_publish_3_10_and_ez_find_1_0_0beta2_for_ez_publish_4_0_released</link>
      <description>A new product in the eZ family of open-source solutions...</description>
      <author>nospam@ez.no (Kåre)</author>
      <guid isPermaLink="true">http://ez.no/ezfind/news/ez_find_1_0_2_for_ez_publish_3_10_and_ez_find_1_0_0beta2_for_ez_publish_4_0_released</guid>
      <pubDate>Wed, 04 Jul 2007 14:35:00 +0000</pubDate>
    </item>
  </channel>
</rss>

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).

Step 6. Save the XML feed to a file

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

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.

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:

<link rel="alternate" type="application/rss+xml" href="http://ez.no/feeds/news.xml"
title="eZ news feed" />

Or this line for ATOM feeds:

<link rel="alternate" type="application/atom+xml" href="http://ez.no/feeds/news.xml"
title="eZ news feed" />

In modern browsers the user will be informed (usually via a small icon like feed icon 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:

<a type="application/rss+xml" href="http://ez.no/feeds/news.xml"
title="eZ news feed">RSS feed</a>

Or this line for ATOM feeds:

<a type="application/atom+xml" href="http://ez.no/feeds/news.xml"
title="eZ news feed">ATOM feed</a>

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 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:

Feed title
Feed link
Feed published date
Feed author name
Feed author email
Feed description

Item 1 title
Item 1 link
Item 1 published date
Item 1 author name
Item 1 author email
Item 1 description

Item 2 title
Item 2 link
Item 2 published date
Item 2 author name
Item 2 author email
Item 2 description

.. etc

An example of an input text file:

eZ news feed
http://ez.no
Wed, 05 Mar 2008 14:28:45 +0000
Derick
nospam@ez.no
This RSS feed contains news feeds for eZ Publish and eZ Components.

eZ Components 2007.1 released
http://ezcomponents.org/resources/news/news-2007-07-02
Mon, 02 Jul 2007 11:36:45 +0000
Derick
nospam@ez.no
The new release of eZ Components include Workflow, Authentication...

eZ Publish 4.0 released
http://ez.no/company/news/first_stable_ez_publish_4_0_release_for_php_5
Tue, 03 Jul 2007 16:59:00 +0000
Ole
nospam@ez.no
The new release of eZ Publish is based on PHP 5....

eZ Find 1.0 released
http://ez.no/ezfind/news/ez_find_1_0_2_for_ez_publish_3_10_and_ez_find_1_0_0beta2_for_ez_publish_4_0_released
Wed, 04 Jul 2007 14:35:00 +0000
Kåre
nospam@ez.no
A new product in the eZ family of open-source solutions...

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.

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

php feed_creator.php rss2 data/news.txt

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

<?xml version="1.0" encoding="utf-8"?>
<rss version="2.0">
  <channel>
    <title>eZ news feed</title>
    <link>http://ez.no</link>
    <description>This RSS feed contains news feeds for eZ Publish and eZ Components.</description>
    <managingEditor>nospam@ez.no (Derick)</managingEditor>
    <pubDate>Wed, 05 Mar 2008 14:28:45 +0000</pubDate>
    <lastBuildDate>Tue, 11 Mar 2008 09:46:43 +0000</lastBuildDate>
    <generator>eZ Components Feed dev (http://ezcomponents.org/docs/tutorials/Feed)</generator>
    <docs>http://www.rssboard.org/rss-specification</docs>
    <item>
      <title>eZ Components 2007.1 released</title>
      <link>http://ezcomponents.org/resources/news/news-2007-07-02</link>
      <description>The new release of eZ Components include Workflow, Authentication...</description>
      <author>nospam@ez.no (Derick)</author>
      <guid isPermaLink="true">http://ezcomponents.org/resources/news/news-2007-07-02</guid>
      <pubDate>Mon, 02 Jul 2007 11:36:45 +0000</pubDate>
    </item>
    <item>
      <title>eZ Publish 4.0 released</title>
      <link>http://ez.no/company/news/first_stable_ez_publish_4_0_release_for_php_5</link>
      <description>The new release of eZ Publish is based on PHP 5....</description>
      <author>nospam@ez.no (Ole)</author>
      <guid isPermaLink="true">http://ez.no/company/news/first_stable_ez_publish_4_0_release_for_php_5</guid>
      <pubDate>Tue, 03 Jul 2007 16:59:00 +0000</pubDate>
    </item>
    <item>
      <title>eZ Find 1.0 released</title>
      <link>http://ez.no/ezfind/news/ez_find_1_0_2_for_ez_publish_3_10_and_ez_find_1_0_0beta2_for_ez_publish_4_0_released</link>
      <description>A new product in the eZ family of open-source solutions...</description>
      <author>nospam@ez.no (Kåre)</author>
      <guid isPermaLink="true">http://ez.no/ezfind/news/ez_find_1_0_2_for_ez_publish_3_10_and_ez_find_1_0_0beta2_for_ez_publish_4_0_released</guid>
      <pubDate>Wed, 04 Jul 2007 14:35:00 +0000</pubDate>
    </item>
  </channel>
</rss>

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 RC planes, with information about planes, competitions, tutorials and tips
  • an author (called managerEditor in RSS2): 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 be 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.
  • 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: 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:

$feed = new ezcFeed( 'rss2' );

$feed->title = 'Flight of the RC plane';
$feed->description = 'A podcast for fans of RC planes, with information about planes, competitions, tutorials and tips';
$feed->author = 'rcplanes@example.com (Derick)';

$link = $feed->add( 'link' );
$link->set( '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:

$iTunes = $feed->addModule( 'iTunes' );

$iTunes->keywords = 'RC planes,gadgets,flying';
$iTunes->explicit = 'yes';
$iTunes->subtitle = 'Competitions, tutorials and tips';

// add an image for the podcast
$image = $iTunes->add( 'image' );
$image->href = 'http://rcplanes.example.com/images/rc_plane_big.jpg';

// add the podcast in the category Technology->Gadgets
$category = $iTunes->add( 'category' );
$category->text = 'Technology';
$subCategory = $category->add( 'category' );
$subCategory->text = '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 &amp; (eg. Society &amp; 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:

$item = $feed->add( 'item' );

$item->title = 'Flying an RC plane indoors';
$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';
$item->author = 'rcplanes@example.com (Derick)';
$item->published = 'Fri, 04 Jan 2008 11:18:34 +0100';

$link = $item->add( 'link' );
$link->set( 'http://rcplanes.example.com/articles/fly-an-rc-plane-indoors.html' );

$enclosure = $item->add( 'enclosure' );
$enclosure->url = 'http://rcplanes.example.com/media/003-flying-indoors.mp3';
$enclosure->length = 49099054; // bytes
$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:

$iTunes = $item->addModule( 'iTunes' );

$iTunes->duration = '29:20';
$iTunes->keywords = 'RC planes,office,flying,enemies';

Step 5. Add more items

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

Step 6. Generate the XML feed

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

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

<?xml version="1.0" encoding="utf-8"?>
<rss version="2.0" xmlns:itunes="http://www.itunes.com/dtds/podcast-1.0.dtd">
  <channel>
    <title>Flight of the RC plane</title>
    <link>http://rcplanes.examples.com</link>
    <description>A podcast for fans of RC planes, with information about planes, competitions, tutorials and tips</description>
    <managingEditor>rcplanes@example.com (Derick)</managingEditor>
    <pubDate>Tue, 11 Mar 2008 09:46:59 +0000</pubDate>
    <generator>eZ Components Feed dev (http://ezcomponents.org/docs/tutorials/Feed)</generator>
    <docs>http://www.rssboard.org/rss-specification</docs>
    <itunes:category text="Technology">
      <itunes:category text="Gadgets"/>
    </itunes:category>
    <itunes:explicit>yes</itunes:explicit>
    <itunes:image href="http://rcplanes.example.com/images/rc_plane_big.jpg"/>
    <itunes:keywords>RC planes,gadgets,flying</itunes:keywords>
    <itunes:subtitle>Competitions, tutorials and tips</itunes:subtitle>
    <item>
      <title>Flying an RC plane indoors</title>
      <link>http://rcplanes.example.com/articles/fly-an-rc-plane-indoors.html</link>
      <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</description>
      <author>rcplanes@example.com (Derick)</author>
      <enclosure url="http://rcplanes.example.com/media/003-flying-indoors.mp3" length="49099054" type="audio/x-mp3"/>
      <pubDate>Fri, 04 Jan 2008 11:18:34 +0100</pubDate>
      <itunes:duration>29:20</itunes:duration>
      <itunes:keywords>RC planes,office,flying,enemies</itunes:keywords>
    </item>
    <item>
      <title>The mutant RC flying insect from Hell</title>
      <link>http://rcplanes.example.com/articles/mutant-rc-flying-insect.html</link>
      <description>Gunny just got back from a 2-months vacation in Tokyo with the ultimate RC toy ever (TM) - a mean and noisy RC flying insect based on top-secret Japanese technology</description>
      <author>rcplanes@example.com (Gunny)</author>
      <enclosure url="http://rcplanes.example.com/media/004-mutant-rc-flying-insect.mp3" length="74039198" type="audio/x-mp3"/>
      <pubDate>Tue, 22 Jan 2008 16:58:00 +0100</pubDate>
      <itunes:duration>44:37</itunes:duration>
      <itunes:keywords>RC planes,office,flying,insect,Japanese</itunes:keywords>
    </item>
  </channel>
</rss>

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:

$feed = ezcFeed::parse( 'http://ezcomponents.org/feed/news.xml' );

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:

$feed = ezcFeed::parseContent( $xml );

These things could go wrong when parsing a feed:

URL or file not found
an ezcBaseFileNotFoundException is thrown
XML content is broken or not a feed or unsupported feed
an ezcFeedCanNotParseException is thrown
RSS1 or RSS2 feed without <channel> element
an ezcFeedParseErrorException is thrown

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:

$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:

if ( isset( $feed->title ) )
{
    $title = $feed->title->__toString();
}

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

$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 write:

$title = isset( $feed->title ) ? $feed->title->__toString() : null;
$description = isset( $feed->description ) ? $feed->description->__toString() : null;
$author = isset( $feed->author ) ? $feed->author->__toString() : null;

$links = array();
if ( isset( $feed->links ) )
{
    foreach ( $feed->links as $link )
    {
        $links[] = $link->__toString();
    }
}

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:

$items = array();
foreach ( $feed->items as $item )
{
    $title = isset( $item->title ) ? $item->title->__toString() : null;
    $description = isset( $item->description ) ? $item->description->__toString() : null;
    $published = isset( $item->published ) ? $item->published->getValue()->format( 'c' ) : null;
    $author = isset( $item->author ) ? $item->author->__toString() : null;

    $links = array();
    if ( isset( $item->link ) )
    {
        foreach ( $item->link as $link )
        {
            $links[] = $link->__toString();
        }
    }

    $items[] = array( 'title' => $title,
                      'description' => $description,
                      'author' => $author,
                      'links' => $links );
}

The published element is an ezcFeedElement object encapsulating a DateTime object, so we first get the DateTime object with getValue(), then 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 the 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:

$feed = ezcFeed::parse( 'http://rcplanes.example.com/feed/podcast.xml' );

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:

$feed = ezcFeed::parseContent( $xml );

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:

$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 write:

$title = isset( $feed->title ) ? $feed->title->__toString() : null;
$description = isset( $feed->description ) ? $feed->description->__toString() : null;
$author = isset( $feed->author ) ? $feed->author->__toString() : null;

$links = array();
if ( isset( $feed->links ) )
{
    foreach ( $feed->links as $link )
    {
        $links[] = $link->__toString();
    }
}

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:

if ( $feed->hasModule( 'iTunes' ) )
{
    // process the iTunes module
}

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

if ( isset( $feed->iTunes ) )
{
    // process the iTunes module
}

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

if ( isset( $feed->iTunes ) )
{
    $iTunes = $feed->iTunes;
    $keywords = isset( $iTunes->keywords ) ? $iTunes->keywords->__toString() : null;
    $subtitle = isset( $iTunes->subtitle ) ? $iTunes->subtitle->__toString() : null;
    $image = isset( $iTunes->image ) ? $iTunes->image->href->__toString() : null;

    $categories = array();
    if ( isset( $iTunes->category ) )
    {
        foreach ( $iTunes->category as $category )
        {
            $cat = array( 'text' => $category->text->__toString() );
            if ( isset( $category->category ) )
            {
                $cat['subCategory'] = $category->category[0]->text->__toString();
            }

            $categories[] = $cat;
        }
    }
}

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:

array( 0 => array( 'text' => 'Technology',
                   'subCategory' => 'Gadgets' ),
     );

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

<category text="Technology">
  <category text="Gadgets"/>
</category>

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:

$items = array();
foreach ( $feed->items as $item )
{
    $title = isset( $item->title ) ? $item->title->__toString() : null;
    $description = isset( $item->description ) ? $item->description->__toString() : null;
    $published = isset( $item->published ) ? $item->published->getValue()->format( 'c' ) : null;
    $author = isset( $item->author ) ? $item->author->__toString() : null;

    $links = array();
    if ( isset( $item->link ) )
    {
        foreach ( $item->link as $link )
        {
            $links[] = $link->__toString();
        }
    }

    $media = array();
    if ( isset( $item->enclosure ) )
    {
        $enclosure = $item->enclosure[0];

        $media = array(
           'url' => isset( $enclosure->url ) ? $enclosure->url->__toString() : null,
           'length' => isset( $enclosure->length ) ? $enclosure->length__toString() : null,
           'type' => isset( $enclosure->type ) ? $enclosure->type__toString() : null
           );
    }

    $items[] = array( 'title' => $title,
                      'description' => $description,
                      'author' => $author,
                      'links' => $links,
                      'media' => $media );
}

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:

// ...
    $media = array();
    if ( isset( $item->enclosure ) )
    {
        $enclosure = $item->enclosure[0];

        $media = array(
           'url' => isset( $enclosure->url ) ? $enclosure->url->__toString() : null,
           'length' => isset( $enclosure->length ) ? $enclosure->length__toString() : null,
           'type' => isset( $enclosure->type ) ? $enclosure->type__toString() : null
           );

        if ( isset( $item->iTunes ) )
        {
            $iTunes = $item->iTunes;
            $media['duration'] = isset( $iTunes->duration ) ? $iTunes->duration->__toString : null;
        }
    }
// ...

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). The $media array is added to the $items array to be processed later by the application.

Best practices

This section lists some useful tips for handling feed documents.

Media type

ATOM

All ATOM feeds must be identified with the application/atom+xml media type. Use the getContentType() method of ezcFeed to get this string.

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 of ezcFeed to get this string.

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 of ezcFeed to get this string.

Elements common to all feed types

As each feed type (RSS1, RSS2, ATOM) is different, it can be quite difficult to switch a feed generation application from one feed type to another. It is therefore important to know what elements are common to all feed type, and how the Feed component handles those elements.

The Feed component will ignore elements which are not defined for the current feed type (for example if you set the subtitle element, it will be ignored in RSS1 because it is not defined in the RSS1 specifications).

For a full list of the feed elements and how they are expressed in the Feed component, see the specifications page.

title

  • Required in all feed types.
  • In ATOM it has other attributes, for example type (text, html or xhtml).

link

  • Required in RSS1 and RSS2.
  • In RSS2 and ATOM can appear multiple times, but in RSS1 can appear only one time.

description

  • Required in RSS1 and RSS2.
  • Called subtitle in ATOM (accessed as description through ezcFeed).
  • In ATOM it has other attributes, for example type (text, html or xhtml).

item

  • Optional in RSS2 and ATOM, but RSS1 must have at least one item present.

  • Called entry in ATOM (accessed as item through ezcFeed).

  • These sub-elements of item are present in all feed types:

    title

    Present in all feed types. In ATOM it has other attributes, for example type (text, html or xhtml).

    link

    RSS2 can have multiple links per item.

    description

    Called summary in ATOM (accessed as description through ezcFeed). In ATOM it has other attributes, for example type (text, html or xhtml).

image

  • Optional in all feed types.
  • Called logo in ATOM (accessed as image through ezcFeed).
  • RSS1 and RSS2 have attributes for the image (title, link, url, width, height, description), while ATOM does not have them.

Specifications and RFCs

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

Last updated: Mon, 05 May 2008