# MagpieRSS

## MagpieRSS provides an XML-based (expat) RSS parser in PHP.

MagpieRSS is compatible with RSS .9 through RSS 1.0, and supports the RSS 1.0's modules. (with a few exceptions)

### News!

- MagpieRSS 0.51 Released
  - important bugfix!
  - fix "silent failure" when PHP doesn't have zlib
- Feed On Feeds Uses Magpie
  - server based PHP RSS aggregator built with MagpieRSS
  - easy to install, easy to use.
- MagpieRSS 0.5 Released
  - supports transparent HTTP gzip content negotiation for reduced bandwidth usage
  - quashed some undefined index notices
- MagpieRSS 0.46 Released
  - minor release, more error handling clean up
  - documentation fixes, simpler example
  - new trouble shooting guide for installation and usage problems
- Magpie News as RSS
  - releases, bug fixes, releated stories as an RSS feed
- MagpieRSS Cookbook: Simple PHP RSS How Tos
  - answers some of the most frequently asked Magpie questions
  - feedback, suggestions, requests, recipes welcome
- MagpieRSS 0.4 Released!
  - improved error handling, more flexibility for script authors, backwards compatible
  - new and better examples! including using MagpieRSS and Smarty
  - new Smarty plugin for RSS date parsing

### Why?

I wrote MagpieRSS out of a frustration with the limitations of existing solutions. In particular many of the existing PHP solutions seemed to:

- use a parser based on regular expressions, making for an inherently fragile solution
- only support early versions of RSS
- discard all the interesting information besides item title, description, and link.
- not build proper separation between parsing the RSS and displaying it.

In particular I failed to find any PHP RSS parsers that could sufficiently parse RSS 1.0 feeds, to be useful on the RSS based event feeds we generate at Protest.net.

### Features

- #### Easy to Use

  As simple as:

      require('rss_fetch.inc');
      $rss = fetch_rss($url);

- #### Parses RSS 0.9 - RSS 1.0

  Parses most RSS formats, including support for 1.0 modules and limited namespace support. RSS is packed into convenient data structures; easy to use in PHP, and appropriate for passing to a templating system, like Smarty.

- #### Integrated Object Cache

  Caching the parsed RSS means that the 2nd request is fast, and that including the rss_fetch call in your PHP page won't destroy your performance, and force you to reply on an external cron job. And it happens transparently.

- #### HTTP Conditional GETs

  Save bandwidth and speed up download times with intelligent use of Last-Modified and ETag.
  See HTTP Conditional Get for RSS Hackers

- #### Configurable

  Makes extensive use of constants to allow overriding default behaviour, and installation on shared hosts.

- #### Modular

  - rss_fetch.inc - wraps a simple interface (`fetch_rss()`) around the library.
  - rss_parse.inc - provides the RSS parser, and the RSS object
  - rss_cache.inc - a simple (no GC) object cache, optimized for RSS objects
  - rss_utils.inc - utility functions for working with RSS. currently provides `parse_w3cdtf()`, for parsing W3CDTF into epoch seconds.

### Magpie's approach to parsing RSS

Magpie takes a naive, and inclusive approach. Absolutely non-validating, as long as the RSS feed is well formed, Magpie will cheerfully parse new, and never before seen tags in your RSS feeds.

This makes it very simple support the varied versions of RSS simply, but forces the consumer of a RSS feed to be cognizant of how it is structured.(at least if you want to do something fancy)

Magpie parses a RSS feed into a simple object, with 4 fields: `channel`, `items`, `image`, and `textinput`.

#### channel

`$rss->channel` contains key-value pairs of all tags, without nested tags, found between the root tag (<rdf:RDF>, or <rss>) and the end of the document.

#### items

`$rss->items` is an array of associative arrays, each one describing a single item. An example that looks like:

    <item rdf:about="http://protest.net/NorthEast/calendrome.cgi?span=event&ID=210257">
    <title>Weekly Peace Vigil</title>
    <link>http://protest.net/NorthEast/calendrome.cgi?span=event&ID=210257</link>
    <description>Wear a white ribbon</description>
    <dc:subject>Peace</dc:subject>
    <ev:startdate>2002-06-01T11:00:00</ev:startdate>
    <ev:location>Northampton, MA</ev:location>
    <ev:enddate>2002-06-01T12:00:00</ev:enddate>
    <ev:type>Protest</ev:type>
    </item>

Is parsed, and pushed on the `$rss->items` array as:

    array(
    	title => 'Weekly Peace Vigil',
    	link => 'http://protest.net/NorthEast/calendrome.cgi?span=event&ID=210257',
    	description => 'Wear a white ribbon',
    	dc => array (
    			subject => 'Peace'
    		),
    	ev => array (
    		startdate => '2002-06-01T11:00:00',
    		enddate => '2002-06-01T12:00:00',
    		type => 'Protest',
    		location => 'Northampton, MA'
    	)
    );

#### image and textinput

`$rss->image` and `$rss-textinput` are associative arrays including name-value pairs for anything found between the respective parent tags.

### Usage Examples:

A very simple example would be:

    require_once 'rss_fetch.inc';

    $url = 'http://magpie.sf.net/samples/imc.1-0.rdf';
    $rss = fetch_rss($url);

    echo "Site: ", $rss->channel['title'], "<br>\n";
    foreach ($rss->items as $item ) {
    	$title = $item[title];
    	$url   = $item[link];
    	echo "<a href=$url>$title</a></li><br>\n";
    }

More soon....in the meantime you can check out a cool tool built with MagpieRSS, version 0.1.

### Todos

#### RSS Parser

- Swap in a smarter parser that includes optional support for validation, and required fields.
- Support RSS 2.0 (as much as I'm annoyed by it)
- Improve support for modules that rely on attributes

#### RSS Cache

- Light-weight garbage collection

#### Fetch RSS

- Attempt to auto-detect an RSS feed, given a URL following, much like rssfinder.pydoes.

#### Misc

- More examples
- A test suite
- RSS generation, perhaps with RSSwriter?

### RSS Resources

- RSS Tutorial for Content Publishers and Webmasters is a great place to start.
- RSS Workshop: Publish and Syndicate Your News to the Web is also a good introduction
- Finding More Channels on how to find RSS feeds.
- Hammersley's Content Syndication with XML and RSS is a blog covering RSS current events.
- RSS-DEV mailing list is generally a very helpful, informative space, with the occasional heated debate
- RSS Validator

.

### License and Contact Info

Magpie is distributed under the GPL license...

coded by: kellan (at) protest.net, feedback is always appreciated.