Pressure is nothing more than the shadow of great opportunity. - Michael Johnson

SimpleRss - a class for retrieving and caching RSS feeds

10 years, 5 months ago

Introduction

SimpleRss is designed to provide an easy way to integrate data from an RSS feed into your web site. It fetches feeds using either CURL or file_get_contents, depending on availability, and then uses PHP's standard XML parsing library to read the data and construct a native PHP object which you can reference in your code. There's also the option to cache the parsed data for a specified number of seconds which removes the need to fetch and pass feeds on each page view.

Keeping It Simple

The class focuses on the most important RSS elements and normalises tag names so you don't need to worry about which RSS version or modules your feed uses. If you're looking for an exhaustive implementation of an RSS parser this probably isn't it but if you're simply need a way to display headlines (or full articles) from a feed efficiently and with the minimum of fuss then look no further.

Sample Usage

Here's an example which displays a hyperlinked list of feed headlines:

  1. <?php
  2. require('simple-rss.inc.php');
  3. $oRss = new SimpleRss('http://feeds.feedburner.com/ejeliot/blog-rss', 300);
  4. if ($oRssObject = $oRss->GetRssObject()) {
  5. echo '<ul>';
  6. foreach ($oRssObject->aItems as $oItem) {
  7. echo "<li><a href=\"$oItem->sLink\">$oItem->sTitle</a></li>";
  8. }
  9. echo '</ul>';
  10. }
  11. ?>

Instantiation Parameters

As well as the URL the class supports two optional instantiation parameters which specify the length of time to cache the data (in seconds) and the number of items to retrieve. If not specified the class will cache data for 5 mins and retrieve all items in the specified feed.

Result Format

SimpleRss returns it's data in an object with the following format:

  1. RssObject Object(
  2. [oChannel] => RssChannel Object(
  3. [sTitle] =>
  4. [sDescription] =>
  5. [sLink] =>
  6. [sDate] =>
  7. [sGenerator] =>
  8. [sLanguage] =>
  9. )
  10. [aItems] => Array(
  11. [0] => RssItem Object(
  12. [sTitle] =>
  13. [sDescription] =>
  14. [sLink] =>
  15. [sDate] =>
  16. [sAuthor] =>
  17. [sCategory] =>
  18. )
  19. [1] => RssItem Object(
  20. [sTitle] =>
  21. [sDescription] =>
  22. [sLink] =>
  23. [sDate] =>
  24. [sAuthor] =>
  25. [sCategory] =>
  26. )
  27. [2] => RssItem Object(
  28. [sTitle] =>
  29. [sDescription] =>
  30. [sLink] =>
  31. [sDate] =>
  32. [sAuthor] =>
  33. [sCategory] =>
  34. )
  35. )
  36. )

Fault Tolerance

Assuming you're using CURL and have caching enabled the class provides a couple of mechanisms for preventing a site user from waiting indefinitely for an unresponsive feed and recovering from an XML error in a feed. There are a couple of constants you can set to specify how long the class should wait when connecting to the server hosting a feed and the maximum time the overall fetch should take.

  1. define('HTTP_TIMEOUT', 3); // how long to wait for a connection before aborting, CURL only
  2. define('MAX_HTTP_REQUEST_TIME', 5); // maximum time allowed for completing URL request before aborting, CURL only

Both take an integer value representing a number of seconds. If either value is exceeded the request is aborted and the stale cached version (assuming it exists) is retrieved, re-validated and displayed instead. Re-validating the expired cache ensures that the class won't repeatedly re-request a failing feed.

Similarly if the class is unable to pass the RSS returned the stale cached version is retrieved and re-validated.

Future Enhancements

I'm not planning many, I'd like to keep it simple, but I'll definitely add an option for stripping HTML to cater for situations where you don't need it or don't fully trust the feed you want to include.

Download

You can download the class and support files as a zip here.

Credits

Thanks to Eric for the idea and his input.

Comments

  • Ed -- What a great component. Thank you for putting this together. We implemented this on the homepage for the YUI (Yahoo! User Interface Library) as soon as it was available, and it took just a few minutes to get it installed and working. We use it to bring in our blog feed and recent groups postings on the right hand side of our home page. Really high-quality stuff...thanks again. -Eric

    Eric Miraglia - 11th January 2007 #

  • Good stuff Ed.

    About the only thing I'd change (bearing in mind this is more of a style thing), is the names of the keys in the return array.

    Generally I like to keep the keys/var names of normalised API returns as close as possible to the original API structure. Just for posterity.

    If that's the only thing I can find to whinge about, good job!

    Brad Wright - 13th January 2007 #

  • Eric, Brad - thanks for the positive feedback. Much appreciated. Brad, I take your point about the naming, although I deliberately normalised them so that people could swap feeds in and out without having to change their code.

    Ed Eliot - 13th January 2007 #

  • Hi,

    Is there any reason I'd use this instead of Magpie (by your fellow Yahoo!er Kellan) ?

    Phil Wilson - 1st March 2007 #

  • Phil - this class was supposed to be as lightweight and easy to use as possible. Magpie is certainly more feature rich but perhaps that isn't needed in all situations.

    Ed Eliot - 1st March 2007 #

  • God stuff, Ed!

    Nice, simple class and easy to handle!

    There ist just one problem that encountered with a language that uses unicode characters, e.g. like german. Because the php library libxml internally uses utf-8, all the unicode characters are displayed a little bit destroyed.

    There is an easy workaraound to solve the problem: On every return value of your class use the function utf8_decode(). That's it!

    Greetings from germany! Dan

    Daniel - 7th March 2007 #

  • Daniel - thanks for pointing the problem out - a dumb oversight on my part. Actually you don't need to use utf8_decode(). The xml_parser functions just need to know the input encoding of your RSS feed and output encoding you want to use in your page which can be specified when creating the parser. In PHP 5 only the output encoding is needed as it automatically detects the input.

    I'll update the class to provide a mechanism for setting these.

    Ed Eliot - 7th March 2007 #

  • This class support windows-1251 encoding?

    Saint_Byte - 24th January 2008 #

  • This class sounds interesting! Is it possible to use xml feeds instead of rss feeds? Or is the class built strictly for rss only?

    Eric - 5th June 2008 #

  • Hi, Thank you for the good job. We use at ou company and everyone appreciate it. We just modified one thing on the "addItem" function : we added "$title = htmlspecialchars($title)" because our title contains weird characters which lead our flux non-validate

    4p1C - 18th November 2008 #

  • I have uploaded the files to my local sever and tested it out by chaning the feed URL, default cache directory. But i dont see any cache is generating in the /tmp directory. Could you please guide us how to cache the feed and check for the new feed information for every 1 hr.

    thanks

    Kris - 6th March 2009 #

  • Will SimpleRSS automatically update the expired cache every 'x' minutes, or does it require someone to visit the site to trigger the update?

    Rishi - 9th April 2009 #

  • Sounds cool! Unfortunately your download link times out every time...

    Mirrors anywhere?

    Popo - 2nd July 2010 #

  • I have an rss feed that goes into a .tpl file. I tried to create your caching method but It doesn't seem to work.

    Is there a way to have this working on a .tpl file?

    How can I move the data onto it? the "echo" feature doesn't seem to work.

    _ThaNerd_ - 13th September 2011 #

  • How about image tag?

    ben - 18th February 2014 #

Help make this post better

Notes: Standard BBCode for links, bold, italic and code are supported. rel="nofollow" is added to all links. Your email address will never be displayed on the site.

Back to index