lib/magpie/htdocs/cookbook.html

   1 <html>
   2         <head>
   3         <title>Magie RSS Recipes:  Simple PHP RSS How To</title>
   4         <style>
   5         body {
   6                 font-family:trebuchet MS, trebuchet, verdana, arial, sans-serif;
   7                 font-size: 11px;
   8
   9         }
  10
  11         pre { font-family: "Courier New", monospace;
  12       padding: 1em;
  13       margin: 0.2em 2.5em 0.2em 3em;
  14       background-color: #efeff5;
  15       border: 1px solid #cfcfcf;
  16       white-space: pre;
  17         }
  18
  19         </style>
  20         </head>
  21         <body>
  22 <p>
  23 <h1>MagpieRSS Recipes:  Cooking with Corbies</h1>
  24
  25 <div align="center"><h3><em>"Four and twenty blackbirds baked in a
  26 pie."</em></h3></div>
  27 </p>
  28 <p>
  29 <ol>
  30 <li><a href="#limit">Limit the Number of Headlines(aka Items) Returned</a></li>
  31 <li><a href="#error_message">Display a Custom Error Message if Something Goes
  32 Wrong</a></li>
  33 <li><a href="#write_rss">Generate a New RSS Feed</a></li>
  34 <li><a href="#by_date">Display Headlines More Recent then X Date</a></li>
  35 <li><a href="#from_file">Parse a Local File Containing RSS</a></li>
  36
  37 </ol>
  38 </p>
  39
  40 <a name="limit"></a><h2>1. Limit the Number of Headlines(aka Items) Returned.</h2>
  41
  42 <h3>Problem:</h3>
  43
  44 You want to display the 10 (or 3 or whatever) most recent headlines, but the RSS feed
  45 contains 15.
  46
  47 <h3>Solution:</h3>
  48
  49 <pre>
  50 $num_items = 10;
  51 $rss = fetch_rss($url);
  52
  53 $items = array_slice($rss->items, 0, $num_items);
  54
  55 foreach ( $items as $item ) {
  56 </pre>
  57 <h3>Discussion:</h3>
  58
  59 Rather then trying to limit the number of items Magpie parses, a much simpler,
  60 and more flexible approach is to take a "slice" of the array of items.  And
  61 array_slice() is smart enough to do the right thing if the feed has less items
  62 then $num_items.
  63
  64 <h3>See:</h3> <a href="http://www.php.net/array_slice">http://www.php.net/array_slice</a>
  65 </p>
  66
  67 <a name="error_message"></a><h2>2. Display a Custom Error Message if Something Goes Wrong</h2>
  68
  69 <h3>Problem:</h3>
  70
  71 You don't want Magpie's error messages showing up if something goes wrong.
  72
  73 <h3>Solution:</h3>
  74 <pre>
  75 # Magpie throws USER_WARNINGS only
  76 # so you can cloak these, by only showing ERRORs
  77 error_reporting(E_ERROR);
  78
  79 # check the return value of fetch_rss()
  80
  81 $rss = fetch_rss($url);
  82
  83 if ( $rss ) {
  84 ...display rss feed...
  85 }
  86 else {
  87    echo "An error occured!  " .
  88         "Consider donating more $$$ for restoration of services." .
  89         "&lt;br&gt;Error Message: " . magpie_error();
  90 }
  91 </pre>
  92 <h3>Discussion:</h3>
  93
  94 MagpieRSS triggers a warning in a number of circumstances.  The 2 most common
  95 circumstances are:  if the specified RSS file isn't properly formed (usually
  96 because it includes illegal HTML), or if Magpie can't download the remote RSS
  97 file, and there is no cached version.
  98
  99 If you don't want your users to see these warnings change your error_reporting
 100 settings to only display ERRORs.<br />
 101 Another option is to turn off display_error,
 102 so that WARNINGs, and NOTICEs still go to the error_log but not to the webpages.
 103
 104 You can do this with:
 105
 106 <pre>
 107 # you can also do this in your php.ini file
 108 ini_set('display_errors', 0);
 109 </pre>
 110
 111 <h3>See:</h3>
 112 <a
 113 href="http://www.php.net/error_reporting">http://www.php.net/error_reporting</a>,<br
 114 />
 115 <a href="http://www.php.net/ini_set">http://www.php.net/ini_set</a>, <br />
 116 <a
 117 href="http://www.php.net/manual/en/ref.errorfunc.php">http://www.php.net/manual/en/ref.errorfunc.php</a><br
 118 />
 119
 120 <a name="write_rss"></a><h2>3. Generate a New RSS Feed</h2>
 121
 122 <h3>Problem:</h3>
 123
 124 Create an RSS feed for other people to use.
 125
 126 <h3>Solution:</h3>
 127
 128 Use Useful Inc's <a href="http://usefulinc.com/rss/rsswriter/">RSSWriter</a>.
 129
 130 <h3>Discussion:</h3>
 131
 132 An example of turning a Magpie parsed RSS object back into an RSS file is
 133 forthcoming.  In the meantime RSSWriter is well documented.
 134
 135 <a name="by_date"></a><h2>4. Display Headlines More Recent then X Date</h2>
 136
 137 <h3>Problem:</h3>
 138
 139 You only want to display headlines that were published on, or after a certain
 140 date.
 141
 142
 143 <h3>Solution:</h3>
 144 <pre>
 145 require_once('rss_utils.inc');
 146
 147 # get all headlines published today
 148 $today = getdate();
 149
 150 # today, 12AM
 151 $date = mktime(0,0,0,$today['mon'], $today['mday'], $today['year']);
 152
 153 $rss = fetch_rss($url);
 154
 155 foreach ( $rss->items as $item ) {
 156    $published = parse_w3cdtf($item['dc']['date']);
 157    if ( $published &gt;= $date ) {
 158         echo "Title: " . $item['title'];
 159         echo "Published: " . date("h:i:s A", $published);
 160         echo "&lt;p&gt;";
 161     }
 162 }
 163 </pre>
 164 <h3>Discussion:</h3>
 165
 166 This recipe only works for RSS 1.0 feeds that include the <dc:date> field.
 167 (which is very good RSS style) <br />
 168 <code>parse_w3cdtf()</code> is defined in
 169 <code>rss_utils.inc</code>, and parses RSS style dates into Unix epoch
 170 seconds.
 171
 172 <h3>See: </h3>
 173 <a
 174 href="http://www.php.net/manual/en/ref.datetime.php">http://www.php.net/manual/en/ref.datetime.php</a>
 175
 176 <a name="from_file"></a>
 177 <h2>5. Parse a Local File Containing RSS</h2>
 178 <h3>Problem:</h3>
 179 MagpieRSS provides <code>fetch_rss()</code> which takes a URL and returns a
 180 parsed RSS object, but what if you want to parse a file stored locally that
 181 doesn't have a URL?
 182
 183 <h3>Solution</h3>
 184 <pre>
 185 require_once('rss_parse.inc');
 186
 187 $rss_file = 'some_rss_file.rdf';
 188 $rss_string = read_file($rss_file);
 189 $rss = new MagpieRSS( $rss_string );
 190
 191 if ( $rss and !$rss->ERROR) {
 192 ...display rss...
 193 }
 194 else {
 195     echo "Error: " . $rss->ERROR;
 196 }
 197
 198 # efficiently read a file into a string
 199 # in php >= 4.3.0 you can simply use file_get_contents()
 200 #
 201 function read_file($filename) {
 202     $fh = fopen($filename, 'r') or die($php_errormsg);
 203     $rss_string = fread($fh, filesize($filename) );
 204     fclose($fh);
 205     return $rss_string;
 206 }
 207 </pre>
 208
 209 <h3>Discussion</h3>
 210 Here we are using MagpieRSS's RSS parser directly without the convience wrapper
 211 of <code>fetch_rss()</code>.  We read the contents of the RSS file into a
 212 string, and pass it to the parser constructor.  Notice also that error handling
 213 is subtly different.
 214
 215 <h3>See: </h3>
 216 <a
 217 href="http://www.php.net/manual/en/ref.filesystem.php">http://www.php.net/manual/en/ref.filesystem.php</a>,<br
 218 />
 219 <a
 220 href="http://www.php.net/manual/en/language.oop.php">http://www.php.net/manual/en/language.oop.php</a>
 221
 222 <!--
 223 <a name="link"></a><h2>#. Recipe</h2>
 224 <h3>Problem:</h3>
 225 Problem description
 226 <h3>Solution</h3>
 227 <pre>
 228 code
 229 </pre>
 230 <h3>Discussion/h3>
 231 Discuss code
 232 <h3>See: </h3>
 233 Documentation links:
 234 -->
 235
 236 </body>
 237 </html>