add_filter

Hooks a function or method to a specific filter action.

Description

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

Filters are the hooks that WordPress launches to modify text of various types before adding it to the database or sending it to the browser screen. Plugins can specify that one or more of its PHP functions is executed to modify specific types of text at these times, using the Filter API.

To use the API, the following code should be used to bind a callback to the filter.

In WordPress 1.5.1+, hooked functions can take extra arguments that are set when the matching do_action() or apply_filters() call is run. The $accepted_args allow for calling functions only when the number of args match. Hooked functions can take extra arguments that are set when the matching do_action() or apply_filters() call is run. For example, the action comment_id_not_found will pass any functions that hook onto it the ID of the requested comment.

Note: the function will return true no matter if the function was hooked fails or not. There are no checks for whether the function exists beforehand and no checks to whether the $function_to_add is even a string. It is up to you to take care and this is done for optimization purposes, so everything is as quick as possible.

Returns (boolean)

true

Parameters (4)

0. $tag (string)
The name of the filter to hook the $function_to_add to.
1. $function_to_add (callback)
The name of the function to be called 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 accept (default 1).

Usage

  1. if ( !function_exists( 'add_filter' ) ) { 
  2. require_once ABSPATH . PLUGINDIR . 'buddypress/bp-forums/bbpress/bb-includes/backpress/functions.plugin-api.php'; 
  3.  
  4. // The name of the filter to hook the $function_to_add to. 
  5. $tag = ''; 
  6.  
  7. // The name of the function to be called when the filter is applied. 
  8. $function_to_add = function_name; 
  9.  
  10. // optional. 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. 
  11. $priority = 10; 
  12.  
  13. // optional. The number of arguments the function accept (default 1). 
  14. $accepted_args = 1; 
  15.  
  16. // NOTICE! Understand what this does before running. 
  17. $result = add_filter($tag, $function_to_add, $priority, $accepted_args); 
  18.  

Defined (1)

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

/bp-forums/bbpress/bb-includes/backpress/functions.plugin-api.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;