1. REQUIREMENTS
PHP
PHP 4.2.1 with DOM XML support enabled. You can do this like so: './configure --with-dom'. According to PHP's website, you'll need libxml 2.4.14 or greater. Under RedHat/Mandrake this is a.k.a. libxml2. You may be able to use earlier version of PHP, but the later the better. If you do happen to get it working with an earlier version, let me know
UPDATE (2003.02.27): You should be using PHP 4.3.0, according to PHP's DOMXML reference. Thanks to Nicolas for bringing this to my attention.
Webserver
Apache or some other webserver (phpFeed has been tested on Apache 2.0.40 w/ PHP 4.3.0), though it may very well work with Roxen or MS IIS with PHP.
2. INSTALLATION
Download the latest and greatest, and untar/gzip it somewhere nice and safe. Within the tar/gz, you will notice the demo.php, and the "includes" directory. the demo.php is just an example of what you can do with phpFeed, check it out, see how phpFeed works within it, etc. Then you should check out the configuration file ('includes/phpFeed.config.xml') and set up some new feeds, etc. Note that the first time you view the page, if you have chosen 'otfretrieval', the page will retrieve all the RDF/RSS's that are active in the configuration. If you see nothing, check your error log, and make sure that includes/rdf is chmod'ed 777 or is owned by the user that the webserver runs under (on my system it's 'nobody', on some its 'wwwserver', etc). Point being since the webserver is downloading the files, it needs to be able to write them somewhere.
3. CONFIGURATION
phpFeed.config.xml is the sole configuration file for display options and retrieval of all of the news feeds. The options are broken up into two categories -- "main configuration" and "newsfeed" configuration.
Main Configuration Options
feeddirectory - direct, absolute path where you would like the feeds deposited make sure it exists, and is readable/writable by whomever the httpd daemon runs as (should be 'nobody', but is 'apache' or 'www-data' in some cases)
styleHTML,headerHTML, itemHTML, footerHTML - the header, item and footer HTML that will be show when "showNewsFeed" is called. check the examples for instructions on how to edit these correctly! if you don't have these specified, then nothing will be shown (huzzah!)
otfretrieve - "on the fly" retrieval of new feeds. this will allow the script to pull down new feeds when a user loads the page. this can be VERY slow, especially if the feed isn't available! use at yer own risk 0 for inactive, 1 for active. NOTE: if you turn this off, and then do your updating with the phpFeed.cron.php, then all the RDF's in the feeddirectory will be owned by root. if you switch BACK to on-the-fly retrieval, then you MUST chown/chgrp/chmod all the files in the feeddirectory to nobody/nobody/0777, otherwise the webserver process will not be able to overwrite them with new ones.
Newsfeed Configuration Options
url - the link to the RDF/RSS that you are pulling - it should hopefully be correct
filename - the name that you would like this file to be called when it is stored in 'feeddirectory' (handy when a site names it's backend file 'backend.rdf' - WOW! Original!
interval - the number of $interval (see below) that you'd like to wait before getting a fresh feed
timeunit - either H, M, S, or D (hours, minutes, seconds, days), and combined with $interval, will be the amount of time you would like to wait in order to get a new, fresh feed!
showtitle - show the title of the feed (in Slashdot's case, it's "Slashdot")
showimage - show the image that comes along with the feed. some are ugly (segfault.org), some are nice (salon.com)
showdesc - show the description that comes along with the feed. Slashdot's is "news for nerds, stuff that matters", and freshmeat.net's is some huge long position statement, blah blah. obviously, we don't need to show that.
showinput - some feeds come along with "textinput" stuff - so you can setup a search form. show it?
isactive - 0 for no, 1 for yes. if this tag isn't present, assume active!
debug - 1 will show you a print_r (a good looking text representation of an array) of the items in the newsfeed
Cron-Timed vs. On-The-Fly Retrieval
phpFeed offers you two options for retrieving the RDF/RSS's -- cron-based (timed), and on-the-fly. They are both viable option in their own way, but I thought a short discussion here would be best.
Cron-Retrieval
First off, in order to do the cron-retrieval, you must have built PHP with the CLI (command line interface) (./configure --enable-cli), or have installed the PHP binary from an RPM or DEB or some such. The PHP CLI binary will allow you to run PHP from the command line. This is cool stuff, 'cause now you can do scripting with PHP outside of the browser. It also allows you to run PHP scripts from the shell! I've included includes/phpFeed.cron.sh which could be put into /etc/cron.hourly or whatever, and would automagically update your feeds. make sure you edit the file and put in the correct phpFeed.config.xml path and all, and drop that file in /etc/cron.hourly. Yay!Downsides: you have to have access to cron. i think you can do personal cron stuff, but i'm not sure how. Upsides: no long waits for your users.
On-The-Fly
The updating for the feeds under the "On-The-Fly" configuration updates the feeds when the page is loaded by a browsing user. this doesn't require cron, so it's easier to set-up, but it can take a while, and make the user think "wow, this site is too slow, i'm outta heeeeere". consider this for sites were you can't cron stuff or for low-traffic personal sites.
4. CUSTOMIZING THE LOOK
Styles, Headers, Footers, etc.
In the "Main Configuration Options" up there, you might have noticed the styleHTML, headerHTML, itemHTML and footerHTML options. They point to the stylesheet, header, item body, and footer that will make up a newsfeed's look. There are two example sets of styles, the CSS-DIV style, and the TABLED style.
Demo.php is the file to use to view the CSS-DIV style, and demo-tables.php is the TABLED version. The first thing you have to do is create a loop of some sort to display the newsfeeds. This is showcased in both of the demo files, and you should get the hang of it pretty quickly. Note the use of modulo arithmetic (the % operator) in the demo-tables.php file. A VERY handy thing when it comes to row and paging math. Learn it! (3%2 = 1), (8%3 = 2).
Anatomy of a Newsfeed Layout
Each of the follow is represented in the phpFeed_style.inc.php with it's own CSS style.
phpFeed - the style for the entire feed. you could put a border around it, or specify a width here, or font, whatever.
phpFeedImage - the style for the enclosure around the image.
phpFeedTitle - the style for the enclosure around the title, and the title text itself.
phpFeedTitleLink - the style on the acutal href link to the Feed (e.g. http://slashdot.org). These can also take :hover and :visited modifiers as well.
phpFeedDesc - the style for the text that accompanies the FeedTitle (e.g. News for Nerds...)
phpFeedItems - the style for the enclosure surrounding all of the items (ne' headlines).
phpFeedItemTitle - the style for the enclosure surrounding the individual item
phpFeedItemTitleLink - the style for the link on the ItemTitle, accepts :hover, :visited, etc.
phpFeedItemDesc - the style for the enclosure and text of the ItemDesc (usually a synopsis of the story)
phpFeedFooter - the style for the enclosure at the bottom of the feed (where the filedate is in the examples)