REQUIREMENTS
MapieRSS requires a recent PHP 4+ (developed with 4.2.0)
with xml (expat) support.
Optionally:
* PHP5 with libxml2 support.
* cURL for SSL support
* iconv (preferred) or mb_string for expanded character set support
QUICK START
Magpie consists of 4 files (rss_fetch.inc, rss_parser.inc, rss_cache.inc,
and rss_utils.inc), and the directory extlib (which contains a modified
version of the Snoopy HTTP client)
Copy these 5 resources to a directory named 'magpierss' in the same
directory as your PHP script.
At the top of your script add the following line:
require_once('magpierss/rss_fetch.inc');
Now you can use the fetch_rss() method:
$rss = fetch_rss($url);
Done. That's it. See README for more details on using MagpieRSS.
NEXT STEPS
Important: you'll probably want to get the cache directory working in
order to speed up your application, and not abuse the webserver you're
downloading the RSS from.
Optionally you can install MagpieRSS in your PHP include path in order to
make it available server wide.
Lastly you might want to look through the constants in rss_fetch.inc see if
there is anything you want to override (the defaults are pretty good)
For more info, or if you have trouble, see TROUBLESHOOTING
SETTING UP CACHING
Magpie has built-in transparent caching. With caching Magpie will only
fetch and parse RSS feeds when there is new content. Without this feature
your pages will be slow, and the sites serving the RSS feed will be annoyed
with you.
** Simple and Automatic **
By default Magpie will try to create a cache directory named 'cache' in the
same directory as your PHP script.
** Creating a Local Cache Directory **
Often this will fail, because your webserver doesn't have sufficient
permissions to create the directory.
Exact instructions for how to do this will vary from install to install and
platform to platform. The steps are:
1. Make a directory named 'cache'
2. Give the web server write access to that directory.
An example of how to do this on Debian would be:
1. mkdir /path/to/script/cache
2. chgrp www-data /path/to/script/cache
3. chmod 775 /path/to/script/cache
On other Unixes you'll need to change 'www-data' to what ever user Apache
runs as. (on MacOS X the user would be 'www')
** Cache in /tmp **
Sometimes you won't be able to create a local cache directory. Some reasons
might be:
1. No shell account
2. Insufficient permissions to change ownership of a directory
3. Webserver runs as 'nobody'
In these situations using a cache directory in /tmp can often be a good
option.
The drawback is /tmp is public, so anyone on the box can read the cache
files. Usually RSS feeds are public information, so you'll have to decide
how much of an issue that is.
To use /tmp as your cache directory you need to add the following line to
your script:
define('MAGPIE_CACHE_DIR', '/tmp/magpie_cache');
** Global Cache **
If you have several applications using Magpie, you can create a single
shared cache directory, either using the /tmp cache, or somewhere else on
the system.
The upside is that you'll distribute fetching and parsing feeds across
several applications.
INSTALLING MAGPIE SERVER WIDE
Rather then following the Quickstart instructions which requires you to have
a copy of Magpie per application, alternately you can place it in some
shared location.
** Adding Magpie to Your Include Path **
Copy the 5 resources (rss_fetch.inc, rss_parser.inc, rss_cache.inc,
rss_utils.inc, and extlib) to a directory named 'magpierss' in your include
path. Now any PHP file on your system can use Magpie with:
require_once('magpierss/rss_fetch.inc');
Different installs have different include paths, and you'll have to figure
out what your include_path is.
From shell you can try:
php -i | grep 'include_path'
Alternatley you can create a phpinfo.php file with contains:
Debian's default is:
/usr/share/php
(though more idealogically pure location would be /usr/local/share/php)
Apple's default include path is:
/usr/lib/php
While the Entropy PHP build seems to use:
/usr/local/php/lib/php