Trouble understanding apply_filters()

The question:

In apply_filters()

apply_filters( $tag, $value, $var ... );

I’m having trouble wrapping my head around the $value and $var. I read the codex and it sounds like the $value can be modified, $var not, but I haven’t found any examples of this in the wild. It seems to be used as a way to pass a variable. In which case, what’s the difference between that and the $var?

The Solutions:

Below are the methods you can try. The first solution is probably the best. Try others if the first one doesn’t work. Senior developers aren’t just copying/pasting – they read the methods carefully & apply them wisely to each case.

Method 1

Try to see the function with better names:

apply_filters(
    $filter_name,     // used for add_filter( $filter_name, 'callback' );
    $value_to_change, // the only variable whose value you can change
    $context_1,       // context
    $context_2        // more context
);

So when that function is called as:

// wp-login.php line 94
apply_filters( 'login_body_class', $classes, $action );

You can use …

add_filter( 'login_body_class', 'function_to_change_login_body_class', 10, 2 );

… and get two variables passed to that function. You return the first, the second provides just more context:

function function_to_change_login_body_class( $classes, $action )
{
    if ( 'login' === $action )
        $classes[] = 'foo';

    if ( 'postpass' === $action )
        $classes[] = 'bar';

    return $classes;
}

The additional variables are there to make your decisions easier, not to change those too.

Method 2

What are Filters?

Filters are functions that WordPress passes data through, at certain points in execution, just before taking some action with the data (such as adding it to the database or sending it to the browser screen). Filters sit between the database and the browser (when WordPress is generating pages), and between the browser and the database (when WordPress is adding new posts and comments to the database); most input and output in WordPress passes through at least one filter. WordPress does some filtering by default, and your plugin can add its own filtering.

Hooking into a Filter

In order to let users change some specific data (a value, the output of a function etc.) filter hooks are provided via apply_filters functions.
These filter hooks include the name (or tag) of the filter and at least the function name that is to be used to filter (i.e., alter in some way) the data.

To alter the title of a post, you can use the the_title filter hook, which is defined as follows:

apply_filters( 'the_title', $title, $id );

This means, the filter has the tag/name the_title, the first parameter $title is the data that is to be changed (i.e, the post title) and the second parameter $id is extra information (in this case the post ID).

To display the title of every post in UPPERCASE, for example, you can use the following line:

add_filter('the_title', 'strtoupper');

If we take a look at the add_filter function, we see it is defined as follows:

add_filter( $tag, $function_to_add, $priority, $accepted_args );

We only specified the first and second (required) parameter, while the third and fourth paramter is set to its respective default value (i.e., 10 and 1).

A More Complex Filter

If you want to filter only a certain post, you can use the extra information (in case of this filter: the ID). In order to do so, you have to specify the number of parameters (which is 2 in this case), and in order to do this again, you have to specify the priority parameter (which comes before the number of arguments).

Suppose we want to affect only the title of the post with the ID 42, then it looks like this:

add_filter('the_title', 'my_strtoupper', 10, 2);
function my_strtoupper($title, $id) {
    if (42 === $id) return strtoupper($title);
    return $title;
} // function my_strtoupper

In this case, we have to specify all four available parameters.

What Parameters Do I Have?

To identify the (number of) available parameters of a certain filter, you have to look up where it is defined (in this case: here).


References:


All methods was sourced from stackoverflow.com or stackexchange.com, is licensed under cc by-sa 2.5, cc by-sa 3.0 and cc by-sa 4.0

Leave a Comment