If you’ve been surfing many news or blog sites, you’ve probably come across an RSS icon somewhere on the screen. Real Simple Syndication (RSS) is an XML document format that provides the ability for sites to easily broadcast summaries of their content. News sites find it handy to be able to publish the headlines of their top or most recent news stories, and blog sites find the format useful to publish titles and descriptions of the latest posts. Today, there are a number of applications with the ability to read RSS feeds (or RSS XML documents) and a growing number of web browsers that have built-in RSS support. The purpose of this article is to introduce the RSS 2.0 specification, and to demonstrate how to build a set of classes that build RSS feeds.

Introduction
During the course of this article, I’ll use the phrases ‘RSS document’ and ‘RSS feed’ interchangeably. They’re really the same thing, since a feed is simply an RSS XML document located at a particular URL. It’s up to the provider on how often the RSS feed is refreshed.

The RSS feed could easily be generated by an application on an hourly, daily, or even weekly basis. The application that generates the feed could be written in Perl, PHP, ASP.NET, or Java. It really doesn’t matter, since your web browser, web portal, or RSS reader is just picking up whatever document is located at the URL. Also, in this article, I focus on news stories and news sites since that is a very typical application of RSS
feeds. However, RSS feeds are not limited to just displaying news content – they can be used with any other content that is suitable for syndication on a network.

Without further introduction, I’ll get into the parts that make up the RSS document.

The rss (root) Element
The RSS document has at its root the rss element. The rss element has only one required attribute, called version. The version attribute should be set to 2.0.

The channel Element
A channel is the distribution channel through which items are syndicated. The channel element can have many elements nested inside of it, which are listed in the next two sections.

Required channel Elements
The XML tags listed here are required in the channel element:

• description: this is some meaningful text that gives readers an indication of what the channel is all about. For example, “Example.com’s newest and exciting news, crop prices, and weather report.”
• item: at least one of these is required. Each item should correspond to a news story or another item that is being syndicated.
• link: the URL to the web site, such as http://www.example.com/news
• title: the title of the channel, which usually matches the title of the web site that is being syndicated. An example is ‘Example.com Latest News’.

Optional channel Elements
There are many optional elements that can be nested inside a channel. Each one of them provides detail about the channel.

Following is a description of the channel elements:

• category: you can give the channel one or more categories. A category is a way for you to define the type of content being syndicated by this channel. An example of a category is ‘News’.
• cloud: allows you to register with the RSS channel to be notified when the channel is updated. The cloud element defines a procedure that is called with XML-RPC.
• copyright: copyright information.
• docs: the URL for documentation that covers the RSS format used in the current feed.
• generator: the name of the program used to generate the RSS feed.
• image: an image that can be associated with the RSS feed.
• language: the language of the text in the channel. The value is a code as defined by the W3C (see RFC1766). Examples are ‘en’, ‘fr’, ‘en-US’, or ‘fr-FR’.
• lastBuildDate: the last time the RSS document was generated.
• managingEditor: the e-mail address of someone responsible for the content linked from the RSS feed.
• pubDate: the date the content in the feed was published.
• rating: the rating of the content, which corresponds to the Platform for Internet Content Selection (PICS) rating that was originally used for rating the content of web sites.
• skipDays: a list of days that can be skipped by an application that checks for newer versions of the feed. For instance, if the feed is never written on weekends, put Saturday and Sunday in day elements inside this element.
• skipHours: the hours, on a 24-hour clock, that the RSS feed is not updated. Applications that read this part of the feed can check only on the hours not listed in the hour elements inside this one.
• textInput: text input boxes can be added into the feed for the purposes of searching or limiting your selections. However, this means that if you are writing an RSS feed generator, you have to add support for the textInput element. According to the RSS Advisory Board, most RSS aggregators ignore this element.
• ttl: the number of minutes that a feed should stay in a cache before it is refreshed. If the feed is only updated on a daily basis, this cache can be for an entire day (the value 1440).
• webmaster: the e-mail address of the site’s web master.

The item Element
At least one item element must be contained in the channel, since there is no point in having a channel if nothing is going to be syndicated. An item contains everything worthy of being broadcast with an RSS feed, such as a title and description of a news article, a blog entry, and a newly added file to a repository. At least one of either a title or description element is required, and the rest of the elements listed here are optional:

• author: the e-mail address of the item’s author. If this magazine article were exposed as an RSS item, the value would be ‘mail@nathang.com’.
• category: includes one or more categories that can be used to sort the item.
• comments: a URL of a web page that includes comments on the item’s content.
• description: a description of the item’s content.
• enclosure: an object attached to the item, like the URL for a podcast containing audio related to the item or the URL of a ZIP file that contains source code for a tutorial.
• guid: a Globally Unique Identifier (GUID). It doesn’t need to be in the GUID/UUID format. Instead, it can be a full URL, that will never change, which identifies the item.
• link: the URL of the item. If the item is a news story, it will be the URL of the page that contains the story.
• pubDate: the date the item was published.
• source: a URL link to the original source of the item, if it didn’t actually originate from your site. This allows you to publish links to other content, like the original news article that is discussed in a blog entry.
• title: the title of the item.

The RSS Writer
Up to this point, we’ve just taken a peek at most of the elements included in an RSS document. To me, lists of elements and their descriptions are interesting, but they become more fun when something can be done with them. So I’ll show you how to build a set of classes that will write these elements and create a valid RSS document for you, and you won’t have to worry about building the XML by hand. I’m going to build three classes – one for each of the “main” elements, rss, channel and item, named RSS_Feed, RSS_Channel and RSS_Item, respectively. When building the classes, I’ll start from the bottom up, or from the XML perspective at the innermost element and work my way out.

The RSS_Item class
The RSS_Item class is responsible for serializing data for the item element. Since I’ll be writing classes to do the serialization, I can enforce rules for the RSS specification, like the rule that each item

must have – one of either a title or a description. I’ll accomplish this by setting up these values as parameters in the constructor, and throwing an Exception if at least one of them isn’t supplied. See Listing 1.

I’ve left out some of the PhpDocumentor documentation for brevity; ideally, the documentation should be updated as the class is being built.

In the constructor of the RSS_Item, the code checks to see if the title and description were both blank. If they were both blank, the throw keyword is used to throw an Exception with a useful message to whatever is calling this constructor. It will be up to the code that calls this constructor to handle the exception appropriately. At first, this might flirt very closely with the unpopular notion of using an Exception to handle a condition that isn’t really an exception, but more of a violation of a business rule. In this case though, the constructor needs to do its best to enforce the RSS specification’s rules to ensure that when the object is serialized to XML it will be a valid RSS document.

There is no need to limit setting the title and the description to just the constructor. So I’ve added some access methods that allow the caller to set the title and the description later on. The accessors for the title and the description are included in Listing 2; the source code folder accompanying the magazine lists the accessors for the other RSS item sub-elements.


Listing 1


There’s more – a get and set method for each of the ten different elements that can appear as sub-elements of an item. Only three of the remaining eight elements are not as straightforward as the title and description – category, enclosure and source. These elements have attributes along with their content, so their accessors need to be handled a little differently. The function to set the source up only takes a couple different parameters – the URL of the source and the title of the original source’s channel. The accessor will stuff these values into an array used internally to hold the values for the source.

The getSource() method will return the array. Alternatively, I could avoid returning the array of values and, instead, create two new methods, getSourceURL() and getSourceTitle(). The benefit of doing the latter is that it hides the implementation better so the caller doesn’t have to worry about what the names of the elements are in the array returned by the getSource() method. An example of the new accessors is included in Listing 3.

The accessors for the category and enclosure elements are handled in the same fashion. Once there are accessors for each of the ten sub-elements of an item, it is time to write a method that handles writing the values in the variables out to an XML string. Some of the method are shown in Listing 4.

Testing the RSS_Item Class
Now that the xmlSerialize() method [of the RSS_Item class] is written, it’s time to test it. I’ve written a simple test script in Listing 5 that sets the values of an instance of the RSS_Item class (here $item) and calls the xmlSerialize() method at the end to produce some output.

Listing 2


Note that I had to ‘require’ the RSS_Item.php file, which contains the RSS_Item class. The output of the script produces the item element XML as expected. However, it isn’t very readable when it’s printed to the console because there aren’t any newline characters in the serialization method. That’s okay, because to be a valid RSS XML document it doesn’t need the nice formatting, and it’ll save a little bit of room without having the extra indenting because the file will be a little smaller. There are many ways to format the XML so it is more readable; one way is to use the XML_Beautifier PEAR module to format the string returned by the xmlSerialize() method The formatted XML returned by the test script looks like this:

<item>
<title>Example.com Exciting Headlines</title>
<source url=”http://www.example.com/source/”>Example.com Sources</source>
<link>http://www.example.com/stories/item1</link>
<author>author1@example.com</author>
<comments>These are my comments about the item.</comments>
<author>author1@example.com</author>
<guid>http://www.example.com/stories/item1</guid>
<category domain=”http://category.example.com/”>News</category>
</item>

Listing 3


Listing 4



The RSS_Channel and RSS_Feed classes
The next two classes, RSS_Channel and RSS_Feed, are similar to the RSS_Item class. They have accessors that set up their sub-elements, with the exception that the RSS_Channel class uses the RSS_Item for its item sub-element. Since a channel requires at least one item, the RSS_Channel constructor requires an RSS_Item object passed to it. Once the RSS_Channel object is created, you can add additional items to the channel with the addItem() method. A basic skeleton, without all of the relatively mundane accessor code, is shown in Listing 6.

The RSS_Channel class contains just enough code to write valid RSS documents, because aside from the item element, the only required elements are the title, description, and link elements. The RSS_Feed class is similar to the RSS_Channel class, containing only an array for the channels. The RSS_Feed class’ constructor accepts an RSS_Channel object ; more can be added using the addChannel() method. The RSS_Feed class is included in the sample code. The sample code shown in Listing 7 can be used to write a valid RSS 2.0 document.

Did It Work?
When the RSS_Feed object’s xmlSerialize() method was called, valid RSS was written to the console. The RSS document, created as a result of the test, looks like this:


<rss version=”2.0”>
<channel>
<title>My Channel</title>
<description>This is my channel</description>
<link>http://www.example.com/mychannel</link>
<item>
<title>Example.com Exciting Headlines</title>
<source url=”http://www.example.com/source/”>Example.com Sources</source>
<link>http://www.example.com/stories/item1</link>
<comments>http://www.example.com/comments</comments>
<author>author1@example.com</author>
<guid>http://www.example.com/stories/item1#12</guid>
<category domain=”http://category.example.com/”>News</category>
</item>
<item>
<title>Example.com Boring News
<source url=”http://www.example.com/source/”>Example.com Sources</source>
<link>http://www.example.com/stories/item2</link>
<comments>http://www.example.com/comments</comments>
<author>author2@example.com</author>
<guid>http://www.example.com/stories/item1#1</guid>
<category domain=”http://category.example.com/”>Technology</category>
</item>
</channel>
</rss>

The RSS document output can now be written to a file, either by using the PEAR File package or by using redirection in the command shell to send the output to a file. Once the RSS document is in a file, it can be validated with several different tools. I used a utility called xmllint on the iBook G4 where I did these examples. (On a Microsoft Windows operating system I use Altova’s XMLSpy.) If the RSS document is available from the Internet, which mine was after I tucked it under a folder on my web site, use the Feed Validator tool to validate the RSS feed.

Related Tools
The PEAR::XML_RSS package can be used to parse RSS documents. It is easy to use and provides the ability to quickly add RSS capabilities to a web site. I used the example given in the user documentation on the PEAR web site, but modified the server name. The HTML that was generated from this example, once it was pointed to the RSS document on my computer, looks like this:

<h1>Headlines from <a href=”http://localhost”>Localhost</a></h1>
<ul>
<li><a href=”http://www.example.com/stories/item1”>Example.com
Exciting Headlines</a></li>
<li><a href=”http://www.example.com/stories/item2”>Example.com Boring
News</a></li>
</ul>


Although it’s a rudimentary example, because it isn’t complete HTML, it works to show that the RSS document is being parsed correctly.

So Where Can I Use RSS?
Although I mostly limited my discussion and examples to Newstype items, RSS is not limited to just broadcasting news stories. It can be used for many other purposes, including broadcasting a user’s latest e-mail messages, notifying users of updates in

Listing 5


Listing 6


Listing 7

About the Author

Nathan A. Good lives in the Twin Cities area in Minnesota. He is a contractor with Alliance of Computer Professionals in Bloomington When he isn’t writing software, Nathan enjoys building PCs and servers, reading about and working with new technologies, and trying to get all his friends to make the move to open source software. When he’s not at a computer (which he admits is not often), he spends time with his family, at his church, and at the movies.