WordPress: How to return value when use add_filter?

Question

I've read WordPress codex many times but still don't understand how to return the value if more than one arguments involved. For example:

function bbp_get_topic_title( $topic_id = 0 ) {
    $topic_id = bbp_get_topic_id( $topic_id );
    $title    = get_the_title( $topic_id );

    return apply_filters( 'bbp_get_topic_title', $title, $topic_id );
}

In the above filter, there are 2 arguments. When I add_filter, should I return 2 value, or just return the one I need? Is the following example correct if need the title?

add_filter( 'bbp_get_topic_title', 'my_topic_title', 10, 2 );

function my_topic_title( $title, $topic_id ){
  $title = 'my_example_title';
  return $title;
}

Answer 1

That's absolutely correct.

When registering a filter(or basically calling apply_filters), you should call the function with at least two arguments - name of the filter to be applied and the value to which the filter will be applied.

Any further arguments that you pass to the function will be passed to the filtering functions, but only if they have requested additional arguments. Here's an example:

// Minimal usage for add_filter()
add_filter( 'my_filter', 'my_filtering_function1' );
// We added a priority for our filter - the default priority is 10
add_filter( 'my_filter', 'my_filtering_function2', 11 );
// Full usage of add_filter() - we set a priority for our function and add a number of accepted arguments.
add_filter( 'my_filter', 'my_filtering_function3', 12, 2 );

// Apply our custom filter
apply_filters( 'my_filter', 'content to be filtered', 'argument 2', 'argument 3' );

Given the code above, the content to be filtered will be passed first to my_filtering_function1. This function will only receive the content to be filtered and not the additional arguments.

Then the content will then be passed(after being treated by my_filtering_function1) to my_filtering_function2. Again the function will only receive the first argument.

Finally the content will be passed to the my_filtering_function3 function(as it has been changed by the previous two functions). This time the function will be passed 2 arguments instead(since we specified this), but it won't get the argument 3 argument.

---

See apply_filters() in source.

Answer 2

Practice add_filter and apply_filters

First thing to know is that apply_filters returns its second argument, try this in functions.php:

echo apply_filters('cat_story', 'A cat'); // echoes "A cat"

Second thing to know is that before apply_filters returns "A cat", it applies filters where the "A cat" can be modified, add filters with add_filter:

function add_chasing_mice($cat) {
    return $cat . ' is chasing a mice';
}
add_filter('cat_story', 'add_chasing_mice');

echo apply_filters('cat_story', 'A cat'); // echoes "A cat is chasing a mice"

Third thing to know is that we can add multiple filters:

// #1
function add_chasing_mice($cat) {
    return $cat . ' is chasing a mice';
}
add_filter('cat_story', 'add_chasing_mice');

// #2
function add_something_else($cat) {
    return $cat . ', but it\'s not gonna catch it';
}
add_filter('cat_story', 'add_something_else');

echo apply_filters('cat_story', 'A cat'); // echoes "A cat is chasing a mice but it\'s not gonna catch it"

Forth thing to know is that you can apply filters in specific order:

// #1
function add_chasing_mice($cat) {
    return $cat . ' is chasing a mice';
}
add_filter('cat_story', 'add_chasing_mice', 10); // 10 - is priority

// #2
function add_something_else($cat) {
    return $cat . ', but it\'s not gonna catch it';
}
add_filter('cat_story', 'add_something_else'); // 10 as well, if omitted 

// The filter will be applied before `add_chasing_mice` and `add_something_else`
function replace_the_cat($cat) {
    return 'A dog';
}
add_filter('cat_story', 'replace_the_cat', 9); // 9 < 10, so the filter will be applied first

echo apply_filters('cat_story', 'A cat'); // echoes "A dog is chasing a mice but it's not gonna catch it";

Fifth thing to know is that you can pass additional arguments to your filters:

function add_chasing_mice($cat) {
    return $cat . ' is chasing mice';
}
add_filter('cat_story', 'add_chasing_mice', 10); // 10 - is priority

function add_something_else($cat, $exclam, $wft) {
    return $cat . ', but it\'s not gonna catch it' . $exclam . $wft;
}
add_filter('cat_story', 'add_something_else', 10, 3); // 3 arguments

function replace_the_cat($cat) {
    return 'A dog';
}
add_filter('cat_story', 'replace_the_cat', 9); // 9 < 10, so the filter will be applied first

echo apply_filters('cat_story', 'A cat', '!!!', '!1wTf!?'); 
// 3 arguments are: 'A cat', '!!!', '!1wTf!?'.
// echoes "A dog is chasing a mice but it's not gonna catch it!!!!1wTf!?";