From ae4b445f6eecb7469a7c87dea36b649a2d93287c Mon Sep 17 00:00:00 2001 From: dhawes Date: Sun, 23 Jan 2005 15:50:52 +0000 Subject: [PATCH] magpie help files --- rss/magpie/htdocs/cookbook.html | 237 ++++++++++++++++++ rss/magpie/htdocs/index.html | 419 ++++++++++++++++++++++++++++++++ 2 files changed, 656 insertions(+) create mode 100644 rss/magpie/htdocs/cookbook.html create mode 100644 rss/magpie/htdocs/index.html diff --git a/rss/magpie/htdocs/cookbook.html b/rss/magpie/htdocs/cookbook.html new file mode 100644 index 0000000000..2a18e74c71 --- /dev/null +++ b/rss/magpie/htdocs/cookbook.html @@ -0,0 +1,237 @@ + + + Magie RSS Recipes: Simple PHP RSS How To + + + +

+

MagpieRSS Recipes: Cooking with Corbies

+ +

"Four and twenty blackbirds baked in a +pie."

+

+

+

    +
  1. Limit the Number of Headlines(aka Items) Returned
    2. +
  2. Display a Custom Error Message if Something Goes +Wrong
    3. +
  3. Generate a New RSS Feed
    4. +
  4. Display Headlines More Recent then X Date
    5. +
  5. Parse a Local File Containing RSS
    6. + +
+

+ +

1. Limit the Number of Headlines(aka Items) Returned.

+ +

Problem:

+ +You want to display the 10 (or 3 or whatever) most recent headlines, but the RSS feed +contains 15. + +

Solution:

+ +
+$num_items = 10;
+$rss = fetch_rss($url);
+
+$items = array_slice($rss->items, 0, $num_items);
+
+foreach ( $items as $item ) {
+
+

Discussion:

+ +Rather then trying to limit the number of items Magpie parses, a much simpler, +and more flexible approach is to take a "slice" of the array of items. And +array_slice() is smart enough to do the right thing if the feed has less items +then $num_items. + +

See:

http://www.php.net/array_slice +

+ +

2. Display a Custom Error Message if Something Goes Wrong

+ +

Problem:

+ +You don't want Magpie's error messages showing up if something goes wrong. + +

Solution:

+
+# Magpie throws USER_WARNINGS only
+# so you can cloak these, by only showing ERRORs
+error_reporting(E_ERROR);
+
+# check the return value of fetch_rss()
+
+$rss = fetch_rss($url);
+
+if ( $rss ) {
+...display rss feed...
+}
+else {
+   echo "An error occured!  " .
+        "Consider donating more $$$ for restoration of services." .
+        "<br>Error Message: " . magpie_error();
+}
+
+

Discussion:

+ +MagpieRSS triggers a warning in a number of circumstances. The 2 most common +circumstances are: if the specified RSS file isn't properly formed (usually +because it includes illegal HTML), or if Magpie can't download the remote RSS +file, and there is no cached version. + +If you don't want your users to see these warnings change your error_reporting +settings to only display ERRORs.
+Another option is to turn off display_error, +so that WARNINGs, and NOTICEs still go to the error_log but not to the webpages. + +You can do this with: + +
+# you can also do this in your php.ini file
+ini_set('display_errors', 0);
+
+ +

See:

+http://www.php.net/error_reporting,
+http://www.php.net/ini_set,
+http://www.php.net/manual/en/ref.errorfunc.php
+ +

3. Generate a New RSS Feed

+ +

Problem:

+ +Create an RSS feed for other people to use. + +

Solution:

+ +Use Useful Inc's RSSWriter. + +

Discussion:

+ +An example of turning a Magpie parsed RSS object back into an RSS file is +forthcoming. In the meantime RSSWriter is well documented. + +

4. Display Headlines More Recent then X Date

+ +

Problem:

+ +You only want to display headlines that were published on, or after a certain +date. + + +

Solution:

+
+require_once('rss_utils.inc');
+
+# get all headlines published today
+$today = getdate();
+
+# today, 12AM
+$date = mktime(0,0,0,$today['mon'], $today['mday'], $today['year']);
+
+$rss = fetch_rss($url);
+
+foreach ( $rss->items as $item ) {
+   $published = parse_w3cdtf($item['dc']['date']);
+   if ( $published >= $date ) {
+        echo "Title: " . $item['title'];
+        echo "Published: " . date("h:i:s A", $published);
+        echo "<p>";
+    }
+}
+
+

Discussion:

+ +This recipe only works for RSS 1.0 feeds that include the field. +(which is very good RSS style)
+parse_w3cdtf() is defined in +rss_utils.inc, and parses RSS style dates into Unix epoch +seconds. + +

See:

+http://www.php.net/manual/en/ref.datetime.php + + +

5. Parse a Local File Containing RSS

+

Problem:

+MagpieRSS provides fetch_rss() which takes a URL and returns a +parsed RSS object, but what if you want to parse a file stored locally that +doesn't have a URL? + +

Solution

+
+require_once('rss_parse.inc');
+
+$rss_file = 'some_rss_file.rdf';
+$rss_string = read_file($rss_file);
+$rss = new MagpieRSS( $rss_string );
+
+if ( $rss and !$rss->ERROR) {
+...display rss...
+}
+else {
+    echo "Error: " . $rss->ERROR;
+}
+
+# efficiently read a file into a string
+# in php >= 4.3.0 you can simply use file_get_contents()
+#
+function read_file($filename) {
+    $fh = fopen($filename, 'r') or die($php_errormsg);
+    $rss_string = fread($fh, filesize($filename) );
+    fclose($fh);
+    return $rss_string;
+}
+
+ +

Discussion

+Here we are using MagpieRSS's RSS parser directly without the convience wrapper +of fetch_rss(). We read the contents of the RSS file into a +string, and pass it to the parser constructor. Notice also that error handling +is subtly different. + +

See:

+http://www.php.net/manual/en/ref.filesystem.php,
+http://www.php.net/manual/en/language.oop.php + + + + + diff --git a/rss/magpie/htdocs/index.html b/rss/magpie/htdocs/index.html new file mode 100644 index 0000000000..e6b24b5dbc --- /dev/null +++ b/rss/magpie/htdocs/index.html @@ -0,0 +1,419 @@ + + + Magpie RSS - PHP RSS Parser + + + + + +

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

+

+

Project Info

+ +
+ +

News!

+ +

+

+ +

Why?

+ I wrote MagpieRSS out of a frustration with the limitations of existing + solutions. In particular many of the existing PHP solutions seemed to: + + 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

+ + + + +

+

+ +

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

+ + +

RSS Cache

+ + +

Fetch RSS

+ +

Misc

+ + +

+

+

RSS Resources

+ . +

+

License and Contact Info

+Magpie is distributed under the GPL license... +

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

+SourceForge.net Logo + + + -- 2.39.5