rss_fetch.inc
1: <?php
2: /*
3: * Project: MagpieRSS: a simple RSS integration tool
4: * File: rss_fetch.inc, a simple functional interface
5: to fetching and parsing RSS files, via the
6: function fetch_rss()
7: * Author: Kellan Elliott-McCrea <kellan@protest.net>
8: * License: GPL
9: *
10: * The lastest version of MagpieRSS can be obtained from:
11: * http://magpierss.sourceforge.net
12: *
13: * For questions, help, comments, discussion, etc., please join the
14: * Magpie mailing list:
15: * magpierss-general@lists.sourceforge.net
16: *
17: */
18:
19: // Setup MAGPIE_DIR for use on hosts that don't include
20: // the current path in include_path.
21: // with thanks to rajiv and smarty
22: if (!defined('DIR_SEP')) {
23: define('DIR_SEP', DIRECTORY_SEPARATOR);
24: }
25:
26: if (!defined('MAGPIE_DIR')) {
27: define('MAGPIE_DIR', dirname(__FILE__) . DIR_SEP);
28: }
29:
30: require_once( MAGPIE_DIR . 'rss_parse.inc' );
31: require_once( MAGPIE_DIR . 'rss_cache.inc' );
32:
33: // for including 3rd party libraries
34: define('MAGPIE_EXTLIB', MAGPIE_DIR . 'extlib' . DIR_SEP);
35: require_once( MAGPIE_EXTLIB . 'Snoopy.class.inc');
36:
37:
38: /*
39: * CONSTANTS - redefine these in your script to change the
40: * behaviour of fetch_rss() currently, most options effect the cache
41: *
42: * MAGPIE_CACHE_ON - Should Magpie cache parsed RSS objects?
43: * For me a built in cache was essential to creating a "PHP-like"
44: * feel to Magpie, see rss_cache.inc for rationale
45: *
46: *
47: * MAGPIE_CACHE_DIR - Where should Magpie cache parsed RSS objects?
48: * This should be a location that the webserver can write to. If this
49: * directory does not already exist Mapie will try to be smart and create
50: * it. This will often fail for permissions reasons.
51: *
52: *
53: * MAGPIE_CACHE_AGE - How long to store cached RSS objects? In seconds.
54: *
55: *
56: * MAGPIE_CACHE_FRESH_ONLY - If remote fetch fails, throw error
57: * instead of returning stale object?
58: *
59: * MAGPIE_DEBUG - Display debugging notices?
60: *
61: */
62:
63:
64: /*=======================================================================*\
65: Function: fetch_rss:
66: Purpose: return RSS object for the give url
67: maintain the cache
68: Input: url of RSS file
69: Output: parsed RSS object (see rss_parse.inc)
70:
71: NOTES ON CACHEING:
72: If caching is on (MAGPIE_CACHE_ON) fetch_rss will first check the cache.
73:
74: NOTES ON RETRIEVING REMOTE FILES:
75: If conditional gets are on (MAGPIE_CONDITIONAL_GET_ON) fetch_rss will
76: return a cached object, and touch the cache object upon recieving a
77: 304.
78:
79: NOTES ON FAILED REQUESTS:
80: If there is an HTTP error while fetching an RSS object, the cached
81: version will be return, if it exists (and if MAGPIE_CACHE_FRESH_ONLY is off)
82: \*=======================================================================*/
83:
84: define('MAGPIE_VERSION', '0.72');
85:
86: $MAGPIE_ERROR = "";
87:
88: function fetch_rss ($url) {
89: // initialize constants
90: init();
91:
92: if ( !isset($url) ) {
93: error("fetch_rss called without a url");
94: return false;
95: }
96:
97: // if cache is disabled
98: if ( !MAGPIE_CACHE_ON ) {
99: // fetch file, and parse it
100: $resp = _fetch_remote_file( $url );
101: if ( is_success( $resp->status ) ) {
102: return _response_to_rss( $resp );
103: }
104: else {
105: error("Failed to fetch $url and cache is off");
106: return false;
107: }
108: }
109: // else cache is ON
110: else {
111: // Flow
112: // 1. check cache
113: // 2. if there is a hit, make sure its fresh
114: // 3. if cached obj fails freshness check, fetch remote
115: // 4. if remote fails, return stale object, or error
116:
117: $cache = new RSSCache( MAGPIE_CACHE_DIR, MAGPIE_CACHE_AGE );
118:
119: if (MAGPIE_DEBUG and $cache->ERROR) {
120: debug($cache->ERROR, E_USER_WARNING);
121: }
122:
123:
124: $cache_status = 0; // response of check_cache
125: $request_headers = array(); // HTTP headers to send with fetch
126: $rss = 0; // parsed RSS object
127: $errormsg = 0; // errors, if any
128:
129: // store parsed XML by desired output encoding
130: // as character munging happens at parse time
131: $cache_key = $url . MAGPIE_OUTPUT_ENCODING;
132:
133: if (!$cache->ERROR) {
134: // return cache HIT, MISS, or STALE
135: $cache_status = $cache->check_cache( $cache_key);
136: }
137:
138: // if object cached, and cache is fresh, return cached obj
139: if ( $cache_status == 'HIT' ) {
140: $rss = $cache->get( $cache_key );
141: if ( isset($rss) and $rss ) {
142: // should be cache age
143: $rss->from_cache = 1;
144: if ( MAGPIE_DEBUG > 1) {
145: debug("MagpieRSS: Cache HIT", E_USER_NOTICE);
146: }
147: return $rss;
148: }
149: }
150:
151: // else attempt a conditional get
152:
153: // setup headers
154: if ( $cache_status == 'STALE' ) {
155: $rss = $cache->get( $cache_key );
156: if ( $rss and $rss->etag and $rss->last_modified ) {
157: $request_headers['If-None-Match'] = $rss->etag;
158: $request_headers['If-Last-Modified'] = $rss->last_modified;
159: }
160: }
161:
162: $resp = _fetch_remote_file( $url, $request_headers );
163:
164: if (isset($resp) and $resp) {
165: if ($resp->status == '304' ) {
166: // we have the most current copy
167: if ( MAGPIE_DEBUG > 1) {
168: debug("Got 304 for $url");
169: }
170: // reset cache on 304 (at minutillo insistent prodding)
171: $cache->set($cache_key, $rss);
172: return $rss;
173: }
174: elseif ( is_success( $resp->status ) ) {
175: $rss = _response_to_rss( $resp );
176: if ( $rss ) {
177: if (MAGPIE_DEBUG > 1) {
178: debug("Fetch successful");
179: }
180: // add object to cache
181: $cache->set( $cache_key, $rss );
182: return $rss;
183: }
184: }
185: else {
186: $errormsg = "Failed to fetch $url ";
187: if ( $resp->status == '-100' ) {
188: $errormsg .= "(Request timed out after " . MAGPIE_FETCH_TIME_OUT . " seconds)";
189: }
190: elseif ( $resp->error ) {
191: # compensate for Snoopy's annoying habbit to tacking
192: # on '\n'
193: $http_error = substr($resp->error, 0, -2);
194: $errormsg .= "(HTTP Error: $http_error)";
195: }
196: else {
197: $errormsg .= "(HTTP Response: " . $resp->response_code .')';
198: }
199: }
200: }
201: else {
202: $errormsg = "Unable to retrieve RSS file for unknown reasons.";
203: }
204:
205: // else fetch failed
206:
207: // attempt to return cached object
208: if ($rss) {
209: if ( MAGPIE_DEBUG ) {
210: debug("Returning STALE object for $url");
211: }
212: return $rss;
213: }
214:
215: // else we totally failed
216: error( $errormsg );
217:
218: return false;
219:
220: } // end if ( !MAGPIE_CACHE_ON ) {
221: } // end fetch_rss()
222:
223: /*=======================================================================*\
224: Function: error
225: Purpose: set MAGPIE_ERROR, and trigger error
226: \*=======================================================================*/
227:
228: function error ($errormsg, $lvl=E_USER_WARNING) {
229: global $MAGPIE_ERROR;
230:
231: // append PHP's error message if track_errors enabled
232: if ( isset($php_errormsg) ) {
233: $errormsg .= " ($php_errormsg)";
234: }
235: if ( $errormsg ) {
236: $errormsg = "MagpieRSS: $errormsg";
237: $MAGPIE_ERROR = $errormsg;
238: trigger_error( $errormsg, $lvl);
239: }
240: }
241:
242: function debug ($debugmsg, $lvl=E_USER_NOTICE) {
243: trigger_error("MagpieRSS [debug] $debugmsg", $lvl);
244: }
245:
246: /*=======================================================================*\
247: Function: magpie_error
248: Purpose: accessor for the magpie error variable
249: \*=======================================================================*/
250: function magpie_error ($errormsg="") {
251: global $MAGPIE_ERROR;
252:
253: if ( isset($errormsg) and $errormsg ) {
254: $MAGPIE_ERROR = $errormsg;
255: }
256:
257: return $MAGPIE_ERROR;
258: }
259:
260: /*=======================================================================*\
261: Function: _fetch_remote_file
262: Purpose: retrieve an arbitrary remote file
263: Input: url of the remote file
264: headers to send along with the request (optional)
265: Output: an HTTP response object (see Snoopy.class.inc)
266: \*=======================================================================*/
267: function _fetch_remote_file ($url, $headers = "" ) {
268: // Snoopy is an HTTP client in PHP
269: $client = new Snoopy();
270: $client->agent = MAGPIE_USER_AGENT;
271: $client->read_timeout = MAGPIE_FETCH_TIME_OUT;
272: $client->use_gzip = MAGPIE_USE_GZIP;
273: if (is_array($headers) ) {
274: $client->rawheaders = $headers;
275: }
276:
277: @$client->fetch($url);
278: return $client;
279:
280: }
281:
282: /*=======================================================================*\
283: Function: _response_to_rss
284: Purpose: parse an HTTP response object into an RSS object
285: Input: an HTTP response object (see Snoopy)
286: Output: parsed RSS object (see rss_parse)
287: \*=======================================================================*/
288: function _response_to_rss ($resp) {
289: $rss = new MagpieRSS( $resp->results, MAGPIE_OUTPUT_ENCODING, MAGPIE_INPUT_ENCODING, MAGPIE_DETECT_ENCODING );
290:
291: // if RSS parsed successfully
292: if ( $rss and !$rss->ERROR) {
293:
294: // find Etag, and Last-Modified
295: foreach($resp->headers as $h) {
296: // 2003-03-02 - Nicola Asuni (www.tecnick.com) - fixed bug "Undefined offset: 1"
297: if (strpos($h, ": ")) {
298: list($field, $val) = explode(": ", $h, 2);
299: }
300: else {
301: $field = $h;
302: $val = "";
303: }
304:
305: if ( $field == 'ETag' ) {
306: $rss->etag = $val;
307: }
308:
309: if ( $field == 'Last-Modified' ) {
310: $rss->last_modified = $val;
311: }
312: }
313:
314: return $rss;
315: } // else construct error message
316: else {
317: $errormsg = "Failed to parse RSS file.";
318:
319: if ($rss) {
320: $errormsg .= " (" . $rss->ERROR . ")";
321: }
322: error($errormsg);
323:
324: return false;
325: } // end if ($rss and !$rss->error)
326: }
327:
328: /*=======================================================================*\
329: Function: init
330: Purpose: setup constants with default values
331: check for user overrides
332: \*=======================================================================*/
333: function init () {
334: if ( defined('MAGPIE_INITALIZED') ) {
335: return;
336: }
337: else {
338: define('MAGPIE_INITALIZED', true);
339: }
340:
341: if ( !defined('MAGPIE_CACHE_ON') ) {
342: define('MAGPIE_CACHE_ON', true);
343: }
344:
345: if ( !defined('MAGPIE_CACHE_DIR') ) {
346: define('MAGPIE_CACHE_DIR', './cache');
347: }
348:
349: if ( !defined('MAGPIE_CACHE_AGE') ) {
350: define('MAGPIE_CACHE_AGE', 60*60); // one hour
351: }
352:
353: if ( !defined('MAGPIE_CACHE_FRESH_ONLY') ) {
354: define('MAGPIE_CACHE_FRESH_ONLY', false);
355: }
356:
357: if ( !defined('MAGPIE_OUTPUT_ENCODING') ) {
358: define('MAGPIE_OUTPUT_ENCODING', 'ISO-8859-1');
359: }
360:
361: if ( !defined('MAGPIE_INPUT_ENCODING') ) {
362: define('MAGPIE_INPUT_ENCODING', null);
363: }
364:
365: if ( !defined('MAGPIE_DETECT_ENCODING') ) {
366: define('MAGPIE_DETECT_ENCODING', true);
367: }
368:
369: if ( !defined('MAGPIE_DEBUG') ) {
370: define('MAGPIE_DEBUG', 0);
371: }
372:
373: if ( !defined('MAGPIE_USER_AGENT') ) {
374: $ua = 'MagpieRSS/'. MAGPIE_VERSION . ' (+http://magpierss.sf.net';
375:
376: if ( MAGPIE_CACHE_ON ) {
377: $ua = $ua . ')';
378: }
379: else {
380: $ua = $ua . '; No cache)';
381: }
382:
383: define('MAGPIE_USER_AGENT', $ua);
384: }
385:
386: if ( !defined('MAGPIE_FETCH_TIME_OUT') ) {
387: define('MAGPIE_FETCH_TIME_OUT', 5); // 5 second timeout
388: }
389:
390: // use gzip encoding to fetch rss files if supported?
391: if ( !defined('MAGPIE_USE_GZIP') ) {
392: define('MAGPIE_USE_GZIP', true);
393: }
394: }
395:
396: // NOTE: the following code should really be in Snoopy, or at least
397: // somewhere other then rss_fetch!
398:
399: /*=======================================================================*\
400: HTTP STATUS CODE PREDICATES
401: These functions attempt to classify an HTTP status code
402: based on RFC 2616 and RFC 2518.
403:
404: All of them take an HTTP status code as input, and return true or false
405:
406: All this code is adapted from LWP's HTTP::Status.
407: \*=======================================================================*/
408:
409:
410: /*=======================================================================*\
411: Function: is_info
412: Purpose: return true if Informational status code
413: \*=======================================================================*/
414: function is_info ($sc) {
415: return $sc >= 100 && $sc < 200;
416: }
417:
418: /*=======================================================================*\
419: Function: is_success
420: Purpose: return true if Successful status code
421: \*=======================================================================*/
422: function is_success ($sc) {
423: return $sc >= 200 && $sc < 300;
424: }
425:
426: /*=======================================================================*\
427: Function: is_redirect
428: Purpose: return true if Redirection status code
429: \*=======================================================================*/
430: function is_redirect ($sc) {
431: return $sc >= 300 && $sc < 400;
432: }
433:
434: /*=======================================================================*\
435: Function: is_error
436: Purpose: return true if Error status code
437: \*=======================================================================*/
438: function is_error ($sc) {
439: return $sc >= 400 && $sc < 600;
440: }
441:
442: /*=======================================================================*\
443: Function: is_client_error
444: Purpose: return true if Error status code, and its a client error
445: \*=======================================================================*/
446: function is_client_error ($sc) {
447: return $sc >= 400 && $sc < 500;
448: }
449:
450: /*=======================================================================*\
451: Function: is_client_error
452: Purpose: return true if Error status code, and its a server error
453: \*=======================================================================*/
454: function is_server_error ($sc) {
455: return $sc >= 500 && $sc < 600;
456: }
457:
458: ?>