Trouble understanding apply_filters()

2 comments

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.

   Log in to Reply

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:

   • Plugin API: Filters
   • apply_filters function
   • add_filter function

   Log in to Reply