The syndicated_item_tags hook allows you to write filters which alter or act on the tags that a source feed provides for items to be syndicated by FeedWordPress. Feed tags are the terms provided by the feed in post content using the rel="tag" microformat. They are normally mapped to WordPress tags on the imported post. Note. Any terms provided by standard feed elements such as atom:category, rss:category or dc:subject will normally be filtered through syndicated_item_categories, not through syndicated_item_tags, regardless of whether those terms were “categories” or “tags” on the original syndication source.

The hook passes two parameters to any registered filter functions:

1. $tags, an array containing the tag names for each tag 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 tags to be assigned to the imported post in the WordPress database. The original array of tag names should be returned unchanged if the filter will not modify the categories of the post.

Data Format

Parameters. Feeds provide tags for posts within the content of syndicated posts, using the rel="tag" microformat. Each tag is represented by a plain text name. (The microformat also specifies an identifying URL corresponding to the tag; this is not currently used by FeedWordPress.) 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"><! 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" />
<summary type="html"><![1]]></summary>
<content type="html"
xml:base="http://radgeek.com/gt/2010/12/07/get-the-gun-out-of-the-room/"><![CDATA[
    <p>Sheldon Richman recently published a TGIF column <a href="http://www.thefreemanonline.org/columns/tgif/free-market-in-banking/comment-page-1/#comment-36043"><cite class="article">A Free Market in Banking? Not Even Close</cite></a> in which he points out that when folks like John Quiggin claim that free-market economic ideas have been tried and found wanting in the late economic crisis, they are attacking a <a href="http://radgeek.com/tag/ridiculous-strawman-watch/">Ridiculous Strawman</a> of free-market ideas. There has been, to be sure, an economic crisis, which had something to do with bankers acting recklessly and exploitatively. But not because they were unregulated: there is no such thing as unregulated banking or a free market in money, and never has been at any time in the history of the United States (the Fed is a problem, but it’s far from the first problem). In comments on this story, <a href="http://www.thefreemanonline.org/columns/tgif/free-market-in-banking/comment-page-1/#comment-36043">Shyla asks the musical question</a>:</p>
    <p>[2]</p>
    <p>Tagged: <a rel="tag" href="http://radgeek.com/tag/State+capitalism">State capitalism</a>, 
    <a rel="tag" href="http://radgeek.com/tag/Outreach">Outreach</a>,
    <a rel="tag" href="http://radgeek.com/tag/Regulation">Regulation</a>,
    <a rel="tag" href="http://radgeek.com/tag/Regulatory+capture">Regulatory capture</a>,
    <a rel="tag" href="http://radgeek.com/tag/Sheldon+Richman">Sheldon Richman</a>
    <a rel="tag" href=" href="http://radgeek.com/tag/Shyla">Shyla</a>.</p>
]]></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 ($tags):

array("Regulation", "Regulatory capture", "Sheldon Richman", "Shyla");

N.B.: Note that the $tags parameter here gets only the terms that are included as tags using the rel-tags microformat in the post content. It does not get any of the terms that were provided using the atom:category feed element, even if the terms provided there were treated as “tags” on the source website.

Return value. 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. For example, to remove the tag “Shyla,” add the tag “RadGeek,” and change the tag “Regulatory capture” to “Public Choice,” return the following array:

array("Regulation", "Public Choice", "Sheldon Richman", "RadGeek");

Usage

<?php
add_filter('syndicated_item_tags', $callback, $order, /*arguments=*/ 2);
// $callback should be the name of a callable function with two parameters, such as 'fwp_syndicated_item_tags_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_tags_filter ($tags, $post) {
    // A syndicated item with cats named A, B, and C
    // will get array('A', 'B', 'C') passed in the
    // $categories parameter



    /* ... */



    return $tags;
}

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+: Re-tag "Foo" to "Bar"
Plugin URI: http://feedwordpress.radgeek.com/wiki/syndicated_item_tags
Description: alters the tags of incoming syndicated posts to re-map tag "Foo" to tag "Bar."
Version: 2014.0120
Author: Charles Johnson
Author URI: http://radgeek.com/
License: GPL


/






add_filter(
    /*hook=*/ 'syndicated_item_tags',
    /*function=*/ 'fwp_filter_tags',
    /*order=*/ 10,
    /*arguments=*/ 2
);



/**
 * fwp_filter_tags: Gets the tags provided
 * by the syndication feed and checks for any items
 * tagged as "Foo." If an item matches, instead of
 * appearing under tag "Foo," it is re-assigned to
 * tag "Bar."
 *
 * @param array $tags The tag 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_tags ($tags, $post) {
    $tagsIn = $tags; // save values
    $tags = array(); // start from scratch



    foreach ($tagsIn as $tag) :
        if (strtolower(trim($tag))=='foo') :
            $tags[3] = 'Bar';
        else : // preserve
            $tags[4] = $tag;
        endif;
    endforeach;



    // Send it back
    return $tags;
} /* fwp_filter_tags() */