WordPress: How to return value when use add_filter?
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.
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!?";