SimplePie Plugin for WordPress

The latest version of this plugin has been completely re-written from scratch as a full-scale WordPress plugin, and includes several new features including:

• A configuration pane under the Options tab in the WordPress software.
• “Multifeeds” support.
• MUCH better control over the plugin's output. Supports a simple templating system that allows:
  • Simple, easy-to-use tags for nearly every piece of data that SimplePie can output.
  • Support for multiple templates.
  • Global configuration of default values for several configuration options.
  • Ability to override the defaults for any given feed — including giving a feed it’s own output template.
  • Ability to post-process feed data (e.g. stripping out all content except for images).
• No need to manually set up cache folders.
• Support for internationalized domain names.
• Support for short descriptions is configurable.
• And more!

These instructions assume that you have a basic familiarity with PHP and know how to add a line of PHP code to your own WordPress templates. If you don't, and you're just getting started, we would suggest you take a look at the following documentation and tutorials:

• Introduction to PHP tutorial
• PHP for Beginners
• WordPress: Blog Design and Layout
• WordPress: Theme Development
• WordPress: Customizing your Sidebar

• 2.1: Added support for feed post-processing, better error handling, and fixed issues with installing in the wrong location.
• 2.0: Complete re-write from scratch. Now a full-fledged WordPress plugin complete with control panel.
• 1.2: Added support for the 'showtitle' and 'alttitle' keywords.
• 1.1: Better error handling, and support for the 'error' keyword.
• 1.0: First release.

1. Backup any custom templates and post-processing files you might have.
2. Replace the old plugin folder with the new one.
3. Re-add your custom templates.
4. Make sure that you go into the Options panel, and click “update options” to ensure that new data is entered into the database.

1. Delete all traces of the previous version of the plugin (specifically deleting simplepie_wordpress.php).
2. Wherever you've called SimplePieWP(), you'll likely end up deleting the options you've already set, or converting them to the updated array syntax for setting per-feed options. These new options are discussed below.

There's a link above to download the SimplePie Plugin for WordPress, which already includes the latest release version of SimplePie. When you download them, make sure you know where you've downloaded them to. Once you've done that, unzip them.

The entire plugin folder should be uploaded as-is to your WordPress installation, so that it ends up as wp-content/plugins/simplepie-plugin-for-wordpress.

Log into your WordPress control panel, go to “plugins”, and enable the SimplePie Plugin for WordPress plugin. If you need more help installing WordPress plugins, check out the WordPress plugin installation instructions. From there, you can go to the new Options → SimplePie panel and configure your default settings.

The SimplePie Plugin for WordPress is now installed!

Usage of this plugin has changed radically since version 1.2.x. First off, there's a new options panel that lets you configure your default settings – meaning the settings that SimplePie will obey unless instructed otherwise. This makes things much simpler as you can configure multiple SimplePie instances directly from the options panel.

Let's start with something basic:

<?php echo SimplePieWP('http://simplepie.org'); ?>

This code sample will display the feed using all of the default settings. If you ever want to change the settings for this feed, you could do everything directly from the options panel, as we're not overriding any settings in this example.

We're also utilizing SimplePie's built-in auto-discovery feature to discover the feed for this particular website even though we only entered the website address.

Additionally, you can override the default settings for any specific SimplePie instance by passing parameters directly to the SimplePieWP() function. Here is an example of what passing parameters could look like:

<?php
echo SimplePieWP('http://simplepie.org', array(
	'items' => 5,
	'cache_duration' => 1800,
	'date_format' => 'j M Y, g:i a'
));
?>

In the above example, we've chosen to accept ALL of the default settings (configured in the options panel), but we've overridden the number of items to display, the number of seconds to cache the feed for, and the date formatting on a per-feed basis.

NOTE: Notice that the value for items is a number (specifically an integer), and is not quoted.

As if all of this wasn't enough, the new version of the plugin also supports what we affectionately call “Multifeeds”. This is where you can merge multiple feeds together and sort the items by time and date (sorting by date requires individual items to have a date associated with them). Using Multifeeds is as simple as passing in an array of URLs instead of a single URL:

<?php
echo SimplePieWP(array(
	'http://feeds.feedburner.com/simplepie',
	'http://laughingmeme.org/category/magpie/feed/'
), array(
	'items' => 5,
	'cache_duration' => 1800,
	'date_format' => 'j M Y, g:i a'
));
?>

If you want to override the default settings on a per-feed basis, these are the options that you can set. You would only use these if you want to override the settings from the options panel.

• date_format – [String] The date format to use for English dates. Supports anything that PHP's date() function.
• enable_cache – [Boolean] Whether the given feed should be cached or not.
• enable_order_by_date – [Boolean] Whether to force-reorder items into chronological order. Only works when items have dates associated with them.
• items – [Integer] The number of feed items to display. Will display this value, or all of the items in the feed – whichever is less.
• locale – [String] The locale value to use for displaying localized datestamps.
• local_date_format – [String] The format to use for localized dates.
• processes – [String] The file to use for post-processing the feed. Can use the name of any process listed in the options panel, preferably lowercased with spaces replaced by underscores.
• set_cache_duration – [Integer] The number of seconds to consider the cache file fresh.
• set_max_checked_feeds – [Integer] When using auto-discovery, this is the number of links to check for the existence of a feed.
• set_timeout – [Integer] The number of seconds to wait for a remote website while fetching a feed.
• strip_attributes – [String] A space-delimited list of HTML attributes to remove from the feed's content.
• strip_htmltags – [String] A space-delimited list of HTML tags to remove from the feed's content.
• template – [String] The template to use for displaying the feed. Can use the name of any template listed in the options panel, preferably lowercased with spaces replaced by underscores.
• truncate_feed_description – [Integer] The number of characters to shorten the feed's description to. Only used with {TRUNCATE_FEED_DESCRIPTION} and {TRUNCATE_ITEM_PARENT_DESCRIPTION}.
• truncate_feed_title – [Integer] The number of characters to shorten the feed's title to. Only used with {TRUNCATE_FEED_TITLE} and {TRUNCATE_ITEM_PARENT_TITLE}.
• truncate_item_description – [Integer] The number of characters to shorten the item's description to. Only used with {TRUNCATE_ITEM_DESCRIPTION}.
• truncate_item_title – [Integer] The number of characters to shorten the item's title to. Only used with {TRUNCATE_ITEM_TITLE}.

Another major new feature in this release is that instead of being locked into a single, simple layout, you can create your own layouts in the form of templates. The following is a list of template tags you can use. Feel free to take a look at the ones that were supplied in the templates folder.

Tags marked with [SP 1.1] are only available in the upcoming SimplePie 1.1 release, or the current in-development trunk builds.

These are tags that are related to the plugin, but not necessarily anything with the SimplePie core.

• {PLUGIN_DIR} – Returns the web URL of the SimplePie plugin directory. This is useful for linking to images or other files that are stored inside the SimplePie plugin directory.

These tags are used for displaying error messages.

• {IF_ERROR_BEGIN} – Marks the beginning of where the error message would display if there was one.
• {IF_ERROR_END} – Marks the end of where the error message would display.
• {ERROR_MESSAGE} – The error message that SimplePie throws.

These tags can be used anywhere in the template.

• {FEED_AUTHOR_EMAIL} – [SP 1.1] Same as $feed->get_author(0)->get_email().
• {FEED_AUTHOR_LINK} – [SP 1.1] Same as $feed->get_author(0)->get_link().
• {FEED_AUTHOR_NAME} – [SP 1.1] Same as $feed->get_author(0)->get_name().
• {FEED_CONTRIBUTOR_EMAIL} – [SP 1.1] Same as $feed->get_contributor(0)->get_email().
• {FEED_CONTRIBUTOR_LINK} – [SP 1.1] Same as $feed->get_contributor(0)->get_link().
• {FEED_CONTRIBUTOR_NAME} – [SP 1.1] Same as $feed->get_contributor(0)->get_name().
• {FEED_COPYRIGHT} – Same as $feed->get_copyright().
• {FEED_DESCRIPTION} – Same as $feed->get_description().
• {FEED_ENCODING} – Same as $feed->get_encoding().
• {FEED_FAVICON} – Same as $feed->get_favicon().
• {FEED_IMAGE_HEIGHT} – Same as $feed->get_image_height().
• {FEED_IMAGE_LINK} – Same as $feed->get_image_link().
• {FEED_IMAGE_TITLE} – Same as $feed->get_image_title().
• {FEED_IMAGE_URL} – Same as $feed->get_image_url().
• {FEED_IMAGE_WIDTH} – Same as $feed->get_image_width().
• {FEED_LANGUAGE} – Same as $feed->get_language().
• {FEED_LATITUDE} – Same as $feed->get_latitude().
• {FEED_LONGITUDE} – Same as $feed->get_longitude().
• {FEED_PERMALINK} – Same as $feed->get_permalink().
• {FEED_TITLE} – Same as $feed->get_title().
• {SUBSCRIBE_URL} – Same as $feed->subscribe_url().
• {TRUNCATE_FEED_DESCRIPTION} – Same as $feed->get_description() except that it obeys the appropriate “truncate text” setting.
• {TRUNCATE_FEED_TITLE} – Same as $feed->get_title() except that it obeys the appropriate “truncate text” setting.

These tags mark the beginning and end of items.

• {ITEM_LOOP_BEGIN} – Marks the beginning of where we should begin looping through items.
• {ITEM_LOOP_END} – Marks the end of where we should stop looping through items.

These are tags that can be used inside the item loop. These will NOT work outside of the item loop and there will be a PHP error if you try.

• {ITEM_AUTHOR_EMAIL} – Same as $item->get_author(0)->get_email().
• {ITEM_AUTHOR_LINK} – Same as $item->get_author(0)->get_link().
• {ITEM_AUTHOR_NAME} – Same as $item->get_author(0)->get_name().
• {ITEM_CATEGORY} – Same as $item->get_category(0)->get_label().
• {ITEM_CONTENT} – Same as $item->get_content().
• {ITEM_CONTRIBUTOR_EMAIL} – [SP 1.1] Same as $item->get_contributor(0)->get_email().
• {ITEM_CONTRIBUTOR_LINK} – [SP 1.1] Same as $item->get_contributor(0)->get_link().
• {ITEM_CONTRIBUTOR_NAME} – [SP 1.1] Same as $item->get_contributor(0)->get_name().
• {ITEM_COPYRIGHT} – [SP 1.1] Same as $item->get_copyright().
• {ITEM_DATE} – Same as $item->get_date().
• {ITEM_DATE_UTC} – Same as $item->get_date() except that a GMT/UTC timestamp is displayed.
• {ITEM_DESCRIPTION} – Same as $item->get_description().
• {ITEM_ENCLOSURE_EMBED} – Same as $item->get_enclosure(0)->native_embed().
• {ITEM_ENCLOSURE_EXTENSION} – Same as $item->get_enclosure(0)->get_extension().
• {ITEM_ENCLOSURE_HANDLER} – Same as $item->get_enclosure(0)->get_handler().
• {ITEM_ENCLOSURE_LENGTH} – Same as $item->get_enclosure(0)->get_length().
• {ITEM_ENCLOSURE_LINK} – Same as $item->get_enclosure(0)->get_link().
• {ITEM_ENCLOSURE_REAL_TYPE} – Same as $item->get_enclosure(0)->get_real_type().
• {ITEM_ENCLOSURE_SIZE} – Same as $item->get_enclosure(0)->get_size().
• {ITEM_ENCLOSURE_TYPE} – Same as $item->get_enclosure(0)->get_type().
• {ITEM_ID} – Same as $item->get_id().
• {ITEM_LATITUDE} – Same as $item->get_latitude().
• {ITEM_LOCAL_DATE} – Same as $item->get_local_date().
• {ITEM_LOCAL_DATE_UTC} – Same as $item->get_local_date() except that a GMT/UTC timestamp is displayed.
• {ITEM_LONGITUDE} – Same as $item->get_longitude().
• {ITEM_PERMALINK} – Same as $item->get_permalink().
• {ITEM_TITLE} – Same as $item->get_title().
• {TRUNCATE_ITEM_DESCRIPTION} – Same as $item->get_description() except that it obeys the appropriate “truncate text” setting.
• {TRUNCATE_ITEM_TITLE} – Same as $item->get_title() except that it obeys the appropriate “truncate text” setting.

When processing a single feed, SimplePie stores information about that feed and makes it available via {FEED_*} tags like {FEED_TITLE} for instance. When you process multiple feeds all at once (via Multifeeds), there isn't a single feed to return data for – instead there are multiple feeds with conflicting data.

So what do we do? If you merge together a feed from Digg and a feed from Slashdot, some items will be from Digg while others are from Slashdot – obviously. As you narrow down a specific item, you can get the feed-level information for that specific item using {ITEM_PARENT_*} tags like {ITEM_PARENT_TITLE} for example.

To use these tags, simply replace the FEED part of each of the feed-level tags above with ITEM_PARENT. {FEED_TITLE} becomes {ITEM_PARENT_TITLE}, {FEED_DESCRIPTION} becomes {ITEM_PARENT_DESCRIPTION} and so on. These tags only work properly between the {ITEM_LOOP_BEGIN} and {ITEM_LOOP_END} tags.

This is used in a few of the sample templates that came bundled with the plugin, so feel free to check them out to get a better feel for how they're used.

New in version 2.1, SimplePie Plugin for WordPress allows you to do post-processing on the feed data. This allows you to do things like strip all content from an item except for images, do profanity censoring, and potentially even strip out advertisements in feeds.

• Post-Processing files should be stored in the processes directory.
• All post-processing functions need to be contained within the SimplePie_PostProcessing class (look at the examples).
• The function to post-process a given template tag should have the same name but lowercased (i.e. {ITEM_CONTENT} would be overridden with function item_content()).

<?php
// We MUST keep this classname.
class SimplePie_PostProcess
{
	// Function name MUST be the same as the template tag we're processing, all lowercase, and MUST accept a single string parameter.
	function item_content($s)
	{
		// Match all images in the content.
		preg_match_all('/<img([^>]*)>/i', $s, $matches);
 
		// Clear out the variable.
		$s = '';
 
		// Loop through all of the *complete* matches (stored in $matches[0]).
		foreach ($matches[0] as $match)
		{
			// Add the images (only) back to $s.
			$s .= $match . '<br />';
		}
 
		// Return $s back out to the plugin.
		return $s;
	}
}
?>

SimplePie assumes that the default WordPress cache folder is writable (which it normally is). If this isn't the case for you, you'll need to change the file permissions for the wp-content/cache directory to be server-writable.

This setting varies from web host to web host. In the past, I've used iPowerWeb, and they required file permissions of 777 in order to be server-writable. Currently, I use Dreamhost, and they need permissions to be set to 755 to be server-writable. Again, if you're not sure, either go ask your host or you can try various settings yourself. The three to try are 755, 775, or 777.

The specific process of how you change your file permissions differs from FTP application to FTP application. On Windows I use FlashFXP, where you find the remote file or folder that you want to change the permissions of, you right-click on it, and choose Attributes (CHMOD). On Mac OS X I use Transmit, where you find the remote file or folder that you want to change the permissions of, you right-click (or ctrl-click for you one-button-mousers) on it, and choose Get Info. Your specific FTP application will most likely be something similar.

According to this post, some PHP installs might have to bump up their memory in PHP.

“Simply increase the php.ini memory allocation. It is set at 8MB by default. I upped mine to 32MB and I was up and running.”