add_filter

Hook a function or method to a specific filter action.

Description

add_filter( (string) $tag, (callable) $function_to_add, (int) $priority = 10, (int) $accepted_args = 1 ); 

WordPress offers filter hooks to allow plugins to modify various types of internal data at runtime.

A plugin can modify data by binding a callback to a filter hook. When the filter is later applied, each bound callback is run in order of priority, and given the opportunity to modify a value by returning a new value.

The following example shows how a callback function is bound to a filter hook.

Note that $example is passed to the callback, (maybe) modified, then returned:

return $example;

Bound callbacks can accept from none to the total number of arguments passed as parameters in the corresponding apply_filters() call.

In other words, if an apply_filters() call passes four total arguments, callbacks bound to it can accept none (the same as 1) of the arguments or up to four. The important part is that the $accepted_args value must reflect the number of arguments the bound callback *actually* opted to accept. If no arguments were accepted by the callback that is considered to be the same as accepting 1 argument. For example:

... return some value;

... return $maybe_modified_value;

*Note:* The function will return true whether or not the callback is valid. It is up to you to take care. This is done for optimization purposes, so everything is as quick as possible.

Parameters (4)

0. $tag (string)
The name of the filter to hook the $function_to_add callback to.
1. $function_to_add (callable)
The callback to be run when the filter is applied.
2. $priority — Optional. (int) => 10
Used to specify the order in which the functions associated with a particular action are executed. Default 10. Lower numbers correspond with earlier execution, and functions with the same priority are executed in the order in which they were added to the action.
3. $accepted_args — Optional. (int) => 1
The number of arguments the function accepts. Default 1.

Usage

  1. if ( !function_exists( 'add_filter' ) ) { 
  2. require_once ABSPATH . WPINC . '/plugin.php'; 
  3.  
  4. // The name of the filter to hook the $function_to_add callback to. 
  5. $tag = ''; 
  6.  
  7. // The callback to be run when the filter is applied. 
  8. $function_to_add = null; 
  9. $priority = 10; 
  10.  
  11. // Optional. The number of arguments the function accepts. Default 1. 
  12. $accepted_args = 1; 
  13.  
  14. // NOTICE! Understand what this does before running. 
  15. $result = add_filter($tag, $function_to_add, $priority, $accepted_args); 
  16.  

Defined (2)

The function is defined in the following location(s).

/wp-includes/plugin.php  
  1. function add_filter( $tag, $function_to_add, $priority = 10, $accepted_args = 1 ) { 
  2. global $wp_filter, $merged_filters; 
  3.  
  4. $idx = _wp_filter_build_unique_id($tag, $function_to_add, $priority); 
  5. $wp_filter[$tag][$priority][$idx] = array('function' => $function_to_add, 'accepted_args' => $accepted_args); 
  6. unset( $merged_filters[ $tag ] ); 
  7. return true; 
/wp-admin/includes/noop.php  
  1. function add_filter() {}