The syndicated_item_categories hook allows you to write filters which alter or act on the categories that a source feed provides for items to be syndicated by FeedWordPress. Feed categories are the terms provided by standard feed elements such as atom:category, rss:category, or dc:subject.

The hook passes two parameters to any registered filter functions:

1. $categories, an array containing the category names for each category assigned to an item by the syndication feed, and
2. $post, an object of class SyndicatedPost representing the syndicated item as a whole.

The return value for the filter function should be an array containing the names of categories to be assigned to the imported post in the WordPress database. The original array of category names should be returned unchanged if the filter will not modify the categories of the post.

Data Format

Feeds provide categories for posts using standard XML elements such as atom:category, rss:category or dc:subject. Each category is represented by a plain text name. The filter will receive an array whose elements contain each plain text name provided by the source feed. So, for example, an Atom feed with the following atom:entry on it:

<entry>
<author>
<name>Rad Geek</name>
<uri>http://radgeek.com/</uri>
</author>
<title type="html"><![CDATA\[Get the Gun Out of the Room.]]></title>
<link rel="alternate" type="text/html" href="http://radgeek.com/gt/2010/12/07/get-the-gun-out-of-the-room/" />
<id>http://radgeek.com/?p=5527</id>
<updated>2010-12-07T19:57:19Z</updated>
<published>2010-12-07T19:49:24Z</published>
<category scheme="http://radgeek.com" term="Fellow Workers" />
<category scheme="http://radgeek.com" term="Politics" />
<category scheme="http://radgeek.com" term="Power to the People" />
<category scheme="http://radgeek.com" term="Smash the State" />
<category scheme="http://radgeek.com" term="anarchy" />
<category scheme="http://radgeek.com" term="Banking" />
<category scheme="http://radgeek.com" term="Libertarians" />
<category scheme="http://radgeek.com" term="Limited government" />
<category scheme="http://radgeek.com" term="Minarchism" />
<category scheme="http://radgeek.com" term="Money Monoply" />
<category scheme="http://radgeek.com" term="Outreach" />
<category scheme="http://radgeek.com" term="Regulation" />
<category scheme="http://radgeek.com" term="Regulatory capture" />
<category scheme="http://radgeek.com" term="Sheldon Richman" />
<category scheme="http://radgeek.com" term="Shyla" />
<category scheme="http://radgeek.com" term="State capitalism" />
<summary type="html"><![CDATA\[...]]></summary>
<content type="html"
xml:base="http://radgeek.com/gt/2010/12/07/get-the-gun-out-of-the-room/"><!\[CDATA\[
...
]]></content>
<link rel="replies" type="text/html" href="http://radgeek.com/gt/2010/12/07/get-the-gun-out-of-the-room/#comments" thr:count="2"/>
<link rel="replies" type="application/atom+xml" href="http://radgeek.com/gt/2010/12/07/get-the-gun-out-of-the-room/feed/" thr:count="2"/>
<thr:total>2</thr:total>
</entry>

… a filter function hooked onto syndicated_item_categories will receive the following value in its first parameter ($categories):

array("Fellow Workers", "Politics", "Power to the People",
  "Smash the State", "anarchy", "Banking", "Libertarians",
  "Limited government", "Minarchism", "Money Monoply",
  "Outreach", "Regulation", "Regulatory capture",
  "Sheldon Richman", "Shyla", "State capitalism")

The return value from the filter function should be provided in the same format — i.e., as an array of strings, with each element the name of a category to assign to the syndicated item.

Usage

<?php
add_filter('syndicated_item_categories', $callback, $order, /*arguments=*/ 2);
// $callback should be the name of a callable function with two parameters, such as 'fwp_syndicated_item_categories_filter'
// $order should be an integer value; a lower value means that the filter will be executed sooner; a higher value means later



function fwp_syndicated_item_categories_filter ($categories, $post) {
    // A syndicated item with cats named A, B, and C
    // will get array('A', 'B', 'C') passed in the
    // $categories parameter



    /* ... */



    return $categories;
}

Sample

This example filter will filter incoming categories so that syndicated articles that the feed assigns to the category “Foo” will instead be treated as if they had been assigned to the category “Bar”.

<?php
/*
Plugin Name: FWP+: Recategorize "Foo" to "Bar"
Plugin URI: http://feedwordpress.radgeek.com/wiki/syndicateditemcategories
Description: alters the categories of incoming syndicated posts to re-map category "Foo" to category "Bar."
Version: 2010.1212
Author: Charles Johnson
Author URI: http://radgeek.com/
License: GPL


/






add_filter(
    /*hook=*/ 'syndicated_item_categories',
    /*function=*/ 'fwp_filter_categories',
    /*order=*/ 10,
    /*arguments=*/ 2
);



/**
 * fwp_filter_categories: Gets the categories provided
 * by the syndication feed and checks for any items
 * categorized as "Foo." If an item matches, instead of
 * appearing under category "Foo," it is re-assigned to
 * category "Bar."
 *
 * @param array $categories The category names assigned to the syndicated item.
 * @param SyndicatedPost $post An object representing the syndicated post.
 *  The syndicated item data is contained in $post->item
 *  The syndication feed channel data is contained in $post->feed
 *  The subscription data is contained in $post->link
 * @return array The new categories to assign to the syndicated item.
 */
function fwp_filter_categories ($categories, $post) {
    $catsIn = $categories; // save values
    $categories = array(); // start from scratch



    foreach ($catsIn as $cat) :
        if (strtolower(trim($cat))=='foo') :
            $categories[1] = 'Bar';
        else : // preserve
            $categories[2] = $cat;
        endif;
    endforeach;



    // Send it back
    return $categories;
} /* fwp_filter_categories() */