lib/magpie/htdocs/index.html

   1 <html>
   2   <head>
   3   <title>Magpie RSS - PHP RSS Parser</title>
   4   <link rel="alternate" type="application/rss+xml" title="RSS"
   5         href="http://laughingmeme.org/magpierss.rdf" />
   6   <style>
   7         body {
   8                 font-family:trebuchet MS, trebuchet, verdana, arial, sans-serif;
   9                 font-size: 11px;
  10
  11         }
  12
  13         pre { font-family: "Courier New", monospace;
  14       padding: 1em;
  15       margin: 0.2em 2.5em 0.2em 3em;
  16       background-color: #efeff5;
  17       border: 1px solid #cfcfcf;
  18       white-space: pre;
  19  }
  20
  21         li.news {
  22                 padding-bottom:15px;
  23         }
  24
  25         a.nav { color: #FFFFFF; }
  26
  27         div.nav {
  28                 width: 2in;
  29                 float: right;
  30                 border: 2px solid #cfcfcf;
  31                 padding: 5px;
  32                 background-color: #996699;
  33         }
  34
  35   </style>
  36   </head>
  37   <body>
  38         <img src="magpie-photo.jpg">
  39         <h1>MagpieRSS</h1>
  40         <p>
  41         <h2>MagpieRSS provides an XML-based (expat) RSS parser in PHP.</h2>
  42         <p>
  43         MagpieRSS is compatible with RSS .9 through RSS 1.0, and supports the
  44         RSS 1.0's modules. (with a few exceptions)
  45         <p>
  46         <div class="nav">
  47         <center><h3>Project Info</h3></center>
  48         <ul>
  49         <li><a class="nav"
  50 href="http://sourceforge.net/project/showfiles.php?group_id=55691">Download
  51 Magpie</a></li>
  52         <li><a class="nav"
  53 href="http://sourceforge.net/mail/?group_id=55691">Mailing
  54 Lists</a></li>
  55         <li><a class="nav" href="#news">News!</a></li>
  56         <li><a class="nav" href="#why">Why?</a></li>
  57         <li><a class="nav" href="#features">Features</a></li>
  58         <li><a class="nav" href="#philosophy">Philosophy</a></li>
  59         <li><a class="nav" href="#usage">Usage Examples</a></li>
  60         <li><a class="nav" href="/cookbook.html">Cookbook</a></li>
  61         <li><a class="nav" href="#todo">Todo</a></li>
  62 <li style="list-style: none; padding-top: 5px;"><a title="Keep up on MagpieRSS news via RSS" href="http://laughingmeme.org/magpierss.rdf"><img
  63 src="http://magpierss.sf.net/black_grey_magpie_news.gif" border="0"></a></li>
  64 </ul>
  65 </div>
  66         <a name="news"></a>
  67         <h3>News!</h3>
  68         <ul>
  69
  70 <li class="news">
  71                 <a
  72 href="http://sourceforge.net/project/showfiles.php?group_id=55691">MagpieRSS
  73 0.51 Released</a>
  74 <ul>
  75 <li> important bugfix!</li>
  76 <li> fix <a href="http://laughingmeme.org/archives/000811.html
  77 ">"silent failure"</a> when PHP doesn't have zlib</li>
  78 </ul>
  79
  80 </li>
  81
  82 <li class="news">
  83                 <a href="http://minutillo.com/steve/feedonfeeds/">Feed On Feeds Uses Magpie</a>
  84 <ul>
  85 <li> server based PHP RSS aggregator built with MagpieRSS</li>
  86 <li> easy to install, easy to use.</li>
  87 </ul>
  88
  89 </li>
  90
  91
  92 <li class="news">
  93                 <a
  94 href="http://sourceforge.net/project/showfiles.php?group_id=55691&release_id=158897">MagpieRSS
  95 0.5 Released</a>
  96 <ul>
  97 <li> supports transparent HTTP gzip content negotiation for reduced bandwidth usage</li>
  98 <li> quashed some undefined index notices</li>
  99 </ul>
 100
 101 </li>
 102
 103
 104 <li class="news">
 105                 <a
 106 href="http://sourceforge.net/project/showfiles.php?group_id=55691&release_id=139643">MagpieRSS
 107 0.46 Released</a>
 108 <ul>
 109 <li> minor release, more error handling clean up</li>
 110 <li> documentation fixes, simpler example</li>
 111 <li> new <a href="/TROUBLESHOOTING">trouble shooting</a> guide for installation and usage problems</a>
 112 </ul>
 113
 114 </li>
 115
 116 <li class="news">
 117                 <a
 118 href="http://laughingmeme.org/magpierss.rdf">Magpie News as RSS</a>
 119 <ul>
 120 <li> releases, bug fixes, releated stories as an RSS feed</li>
 121 </ul>
 122
 123 </li>
 124
 125
 126 <li class="news">
 127                 <a
 128 href="http://magpierss.sourceforge.net/cookbook.html">MagpieRSS
 129 Cookbook: Simple PHP RSS How Tos</a>
 130 <ul>
 131 <li> answers some of the most frequently asked Magpie questions</li>
 132 <li> feedback, suggestions, requests, recipes welcome</li>
 133 </ul>
 134
 135 </li>
 136
 137 <li clas="news">
 138  <a href="http://sourceforge.net/project/showfiles.php?group_id=55691&release_id=134850">MagpieRSS 0.4 Released!</a>
 139 <ul>
 140 <li> improved error handling, more flexibility for script authors,
 141 backwards compatible</li>
 142 <li> new and better examples!  including using MagpieRSS and <a
 143 href="http://smarty.php.net">Smarty</a></li>
 144 <li> new Smarty plugin for RSS date parsing</li>
 145 </ul>
 146 <br />
 147 </li>
 148 <!--
 149 <li class="news">
 150 <a href="http://www.infinitepenguins.net/rss/">Infinite Penguin now
 151 supports Magpie 0.3</a>
 152 <ul>
 153 <li> simple, sophisticated RSS viewer</li>
 154 <li> includes auto-generated javascript ticker from RSS feed</li>
 155 </ul>
 156
 157 </li>
 158
 159
 160 <li class="news">
 161 <a
 162 href="http://traumwind.tierpfad.de/blog/magpie/magpie_alike.php">Traumwind
 163 releases REX backend for MagpieRSS</a>
 164 <ul>
 165 <li>drop in support using regex based XML parser</li>
 166 <li>parses improperly formed XML that chokes expat</li>
 167 </ul>
 168
 169 </li>
 170
 171 <li class="news">
 172                 <a
 173 href="http://sourceforge.net/project/showfiles.php?group_id=55691&release_id=118652">
 174                 MagpieRSS 0.3 Released!</a>
 175                 <ul>
 176                   <li>Support added for
 177                          <a href="http://fishbowl.pastiche.org/archives/001132.html">HTTP
 178                          Conditional GETs</a>.</li>
 179                   <li>See <a href="http://sourceforge.net/project/shownotes.php?group_id=55691&release_id=118652">ChangeLog</a>
 180                   for more info.</li>
 181             </ul>
 182                 </li>
 183                 <li class="news">MagpieRSS 0.2!</a>
 184                 <ul>
 185                   <li>Major clean up of the code.  Easier to use.</li>
 186                   <li>Simpler install on shared hosts.</li>
 187               <li>Better documentation and comments.</li>
 188                 </ul>
 189                 </li>
 190                 <li class="news">We've <a href="http://sourceforge.net/projects/magpierss/">moved to
 191                 Sourceforge!</a></li>
 192         -->
 193         </ul>
 194         </p>
 195         <p>
 196         <a name="why"></a>
 197         <h3>Why?</h3>
 198         I wrote MagpieRSS out of a frustration with the limitations of existing
 199         solutions.   In particular many of the existing PHP solutions seemed to:
 200         <ul>
 201         <li>use a parser based on regular expressions, making for an inherently
 202         fragile solution
 203         <li>only support early versions of RSS
 204         <li>discard all the interesting information besides item title, description,
 205         and link.
 206         <li>not build proper separation between parsing the RSS and displaying it.
 207         </ul>
 208         In particular I failed to find any PHP RSS parsers that could sufficiently
 209         parse RSS 1.0 feeds, to be useful on the RSS based event feeds we generate
 210         at <a href="http://protest.net">Protest.net</a>.
 211         </p>
 212         <p>
 213         <a name="features"></a>
 214         <h3>Features</h3>
 215
 216 <ul>
 217         <li class="toplevel">
 218         <h4>Easy to Use</h4>
 219         As simple as:
 220 <pre>
 221 require('rss_fetch.inc');
 222 $rss = fetch_rss($url);
 223 </pre>
 224
 225         </li>
 226         <li class="toplevel">
 227                 <h4>Parses RSS 0.9 - RSS 1.0</h4>
 228
 229                 Parses most RSS formats, including support for
 230                 <a href="http://www.purl.org/rss/1.0/modules/">1.0 modules</a> and limited
 231                 namespace support.  RSS is packed into convenient data structures; easy to
 232                 use in PHP, and appropriate for passing to a templating system, like
 233                 <a href="http://smarty.php.net">Smarty</a>.
 234         </li>
 235         <li>
 236         <h4>Integrated Object Cache</h4>
 237
 238         Caching the parsed RSS means that the 2nd request is fast, and that
 239 including the rss_fetch call in your PHP page won't destroy your performance,
 240 and force you to reply on an external cron job. And it happens transparently.
 241
 242         </li>
 243         <li>
 244         <h4>HTTP Conditional GETs</h4>
 245
 246         Save bandwidth and speed up download times with intelligent use of
 247         Last-Modified and ETag.<br /> See <a
 248         href="http://fishbowl.pastiche.org/archives/001132.html">HTTP Conditional Get for RSS Hackers</a>
 249         </li>
 250
 251         <li><h4>Configurable</h4>
 252
 253         Makes extensive use of constants to allow overriding default behaviour, and
 254         installation on shared hosts.
 255         </li>
 256         <li><h4>Modular</h4>
 257         <ul>
 258                 <li>rss_fetch.inc - wraps a simple interface (<code>fetch_rss()</code>)
 259                 around the library.
 260                 <li>rss_parse.inc - provides the RSS parser, and the RSS object
 261                 <li>rss_cache.inc - a simple (no GC) object cache, optimized for RSS objects
 262                 <li>rss_utils.inc - utility functions for working with RSS.  currently
 263                 provides <code>parse_w3cdtf()</code>, for parsing <a
 264                 href="http://www.w3.org/TR/NOTE-datetime">W3CDTF</a> into epoch seconds.
 265         </ul>
 266 </ul>
 267
 268
 269         </p>
 270 <p>
 271         <a name="philosophy"></a>
 272         <h3>Magpie's approach to parsing RSS</h3>
 273
 274         Magpie takes a naive, and inclusive approach. Absolutely
 275         non-validating, as long as the RSS feed is well formed, Magpie will
 276         cheerfully parse new, and never before seen tags in your RSS feeds.
 277         </p>
 278         <p>
 279         This makes it very simple support the varied versions of RSS simply, but
 280         forces the consumer of a RSS feed to be cognizant of how it is
 281         structured.(at least if you want to do something fancy)
 282         </p>
 283         <p>
 284         Magpie parses a RSS feed into a simple object, with 4 fields:
 285         <code>channel</code>, <code>items</code>, <code>image</code>, and
 286         <code>textinput</code>.
 287         </p>
 288         <p>
 289         <h4>channel</h4>
 290         <code>$rss->channel</code> contains key-value pairs of all tags, without
 291         nested tags, found between the root tag (&lt;rdf:RDF&gt;, or &lt;rss&gt;)
 292         and the end of the document.
 293         </p>
 294         <p>
 295         <h4>items</h4>
 296         <code>$rss->items</code> is an array of associative arrays, each one
 297         describing a single item.  An example that looks like:
 298         <pre>
 299 &lt;item rdf:about="http://protest.net/NorthEast/calendrome.cgi?span=event&#38;ID=210257"&gt;
 300 &lt;title&gt;Weekly Peace Vigil&lt;/title&gt;
 301 &lt;link&gt;http://protest.net/NorthEast/calendrome.cgi?span=event&#38;ID=210257&lt;/link&gt;
 302 &lt;description&gt;Wear a white ribbon&lt;/description&gt;
 303 &lt;dc:subject&gt;Peace&lt;/dc:subject&gt;
 304 &lt;ev:startdate&gt;2002-06-01T11:00:00&lt;/ev:startdate&gt;
 305 &lt;ev:location&gt;Northampton, MA&lt;/ev:location&gt;
 306 &lt;ev:enddate&gt;2002-06-01T12:00:00&lt;/ev:enddate&gt;
 307 &lt;ev:type&gt;Protest&lt;/ev:type&gt;
 308 &lt;/item&gt;
 309         </pre><p>
 310         Is parsed, and pushed on the <code>$rss-&gt;items</code> array as:
 311         <p><pre>
 312 array(
 313         title =&gt; 'Weekly Peace Vigil',
 314         link =&gt; 'http://protest.net/NorthEast/calendrome.cgi?span=event&#38;ID=210257',
 315         description =&gt; 'Wear a white ribbon',
 316         dc =&gt; array (
 317                         subject =&gt; 'Peace'
 318                 ),
 319         ev =&gt; array (
 320                 startdate =&gt; '2002-06-01T11:00:00',
 321                 enddate =&gt; '2002-06-01T12:00:00',
 322                 type =&gt; 'Protest',
 323                 location =&gt; 'Northampton, MA'
 324         )
 325 );
 326 </pre>
 327 </p>
 328 <p>
 329 <h4>image and textinput</h4>
 330 <code>$rss->image</code> and <code>$rss-textinput</code> are associative arrays
 331 including name-value pairs for anything found between the respective parent
 332 tags.
 333 </p>
 334 <p>
 335 <a name="usage"></a>
 336 <h3>Usage Examples:</h3>
 337
 338 A very simple example would be:
 339 <pre>
 340 require_once 'rss_fetch.inc';
 341
 342 $url = 'http://magpie.sf.net/samples/imc.1-0.rdf';
 343 $rss = fetch_rss($url);
 344
 345 echo "Site: ", $rss->channel['title'], "&lt;br&gt;\n";
 346 foreach ($rss->items as $item ) {
 347         $title = $item[title];
 348         $url   = $item[link];
 349         echo "&lt;a href=$url&gt;$title&lt;/a&gt;&lt;/li&gt;&lt;br&gt;\n";
 350 }
 351 </pre>
 352 More soon....in the meantime you can check out a
 353 <a href="http://www.infinitepenguins.net/rss/">cool tool built with
 354 MagpieRSS</a>, version 0.1.
 355 </p>
 356 <p>
 357 <a name="todo"></a>
 358 <h3>Todos</h3>
 359         <h4>RSS Parser</h4>
 360         <ul>
 361                 <li>Swap in a smarter parser that includes optional
 362                 support for validation, and required fields.</li>
 363
 364                 <li>Support RSS 2.0 (as much as I'm annoyed by it)</li>
 365
 366                 <li>Improve support for modules that rely on attributes</li>
 367         </ul>
 368
 369         <h4>RSS Cache</h4>
 370         <ul>
 371                 <li>Light-weight garbage collection
 372         </ul>
 373
 374         <h4>Fetch RSS</h4>
 375         <ul>
 376         <li>Attempt to <a
 377         href="http://diveintomark.org/archives/2002/08/15.html">auto-detect an
 378         RSS feed</a>, given a URL following, much like <a
 379         href="http://diveintomark.org/projects/misc/rssfinder.py.txt">rssfinder.py</a>does.
 380         </li>
 381         </ul>
 382         <h4>Misc</h4>
 383                 <ul>
 384                 <li>More examples</li>
 385                 <li>A test suite</li>
 386                 <li>RSS generation, perhaps with <a
 387         href="http://usefulinc.com/rss/rsswriter/">RSSwriter</a>?
 388                 </li>
 389                 </ul>
 390
 391 </p>
 392 <p>
 393 <h3>RSS Resources</h3>
 394         <ul>
 395         <li><a href="http://mnot.net/rss/tutorial/">RSS Tutorial for Content Publishers
 396         and Webmasters</a> is a great place to start.
 397         <li><a href="http://gils.utah.gov/rss/">RSS Workshop:  Publish and Syndicate
 398         Your News to the Web</a> is also a good introduction</li>
 399         <li><a href="http://www.disobey.com/amphetadesk/finding_more.html">Finding
 400         More Channels</a> on how to find RSS feeds.
 401         <li>Hammersley's <a href="http://rss.benhammersley.com/">Content Syndication
 402         with XML and RSS</a> is a blog covering RSS current events.
 403         <li><a href="http://groups.yahoo.com/group/rss-dev/">RSS-DEV mailing
 404         list</a> is generally a very helpful, informative space, with the occasional
 405         heated debate
 406         <li><a href="http://feeds.archive.org/validator/">RSS Validator</a>
 407         </ul>.
 408 </p>
 409 <h3>License and Contact Info</h3>
 410 Magpie is distributed under the GPL license...
 411 <p>
 412 coded by: kellan (at) protest.net, feedback is always appreciated.
 413 <p>
 414 <a href="http://sourceforge.net"><img
 415 src="http://sourceforge.net/sflogo.php?group_id=55691&amp;type=3"
 416 width="125" height="37" border="0" alt="SourceForge.net Logo"></a>
 417 <img src="http://laughingmeme.org/magpie_views.gif">
 418 </body>
 419 </html>