Take the 2-minute tour ×
WordPress Development Stack Exchange is a question and answer site for WordPress developers and administrators. It's 100% free, no registration required.

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?

share|improve this question

2 Answers 2

up vote 9 down vote accepted

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.

share|improve this answer
    
Thank you! That clarifies it quite a bit. –  r00tAcc3ss Apr 26 '13 at 15:16
    
If I understand correctly. I don't add a variable to collect the returned value from apply_filters as it is applied to $value_to_change automatically? –  r00tAcc3ss Apr 26 '13 at 15:21
    
@r00tAcc3ss Nothing happens automatically. You have to change the value in your callback. You can also return it unchanged if you want – depending on context. –  toscho Apr 26 '13 at 15:33
    
Oh, yeah. I meant, I don't have to accept the returned value into another variable and assign it to $value. That is done, if I change $value in the hooked function and returned, "automatically." –  r00tAcc3ss Apr 26 '13 at 16:17
    
Nice clear explanation, i don't think i could of summed it up so well. –  t31os Apr 27 '13 at 19:41

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:

share|improve this answer
2  
+1 for a thorough response and impeccable class (nice formatting brochacho)! –  boscho Apr 26 '13 at 15:41
    
Thanks, that's very thorough, but doesn't really explain what I was asking. eg. the difference between the $value variable and $var variable in the filter. –  r00tAcc3ss Apr 26 '13 at 16:20
    
Hm, I would say, it does, but that is, of course, my subjective feeling. I will add some information on the filter and its parameters, though. –  t f Apr 26 '13 at 16:24
    
Thanks! It is very helpful. –  r00tAcc3ss Apr 26 '13 at 18:57

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.