add_filter( string $hook_name, callable $callback, int $priority = 10, int $accepted_args = 1 ): true

Adds a callback function to a filter hook.

Description

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:

function example_callback( $example ) {
    // Maybe modify $example in some way.
    return $example;
}
add_filter( 'example_filter', 'example_callback' );

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:

// Filter call.
$value = apply_filters( 'hook', $value, $arg2, $arg3 );

// Accepting zero/one arguments.
function example_callback() {
    ...
    return 'some value';
}
add_filter( 'hook', 'example_callback' ); // Where $priority is default 10, $accepted_args is default 1.

// Accepting two arguments (three possible).
function example_callback( $value, $arg2 ) {
    ...
    return $maybe_modified_value;
}
add_filter( 'hook', 'example_callback', 10, 2 ); // Where $priority is 10, $accepted_args is 2.

_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

$hook_namestringrequired
The name of the filter to add the callback to.
$callbackcallablerequired
The callback to be run when the filter is applied.
$priorityintoptional
Used to specify the order in which the functions associated with a particular filter are executed.
Lower numbers correspond with earlier execution, and functions with the same priority are executed in the order in which they were added to the filter.

Default:10

$accepted_argsintoptional
The number of arguments the function accepts.

Default:1

Return

true Always returns true.

More Information

  • Hooked functions can take extra arguments that are set when the matching do_action() or apply_filters() call is run. For example, the comment_id_not_found action will pass the comment ID to each callback.
  • Although you can pass the number of $accepted_args, you can only manipulate the $value. The other arguments are only to provide context, and their values cannot be changed by the filter function.
  • You can also pass a class method as a callback.
Static class method:
add_filter( 'media_upload_newtab', array( 'My_Class', 'media_upload_callback' ) );
Instance method:
add_filter( 'media_upload_newtab', array( $this, 'media_upload_callback' ) );
  • You can also pass an an anonymous function as a callback. For example:
add_filter( 'the_title', function( $title ) { return '<strong>' . $title . '</strong>'; } );

Source

function add_filter( $hook_name, $callback, $priority = 10, $accepted_args = 1 ) {
	global $wp_filter;

	if ( ! isset( $wp_filter[ $hook_name ] ) ) {
		$wp_filter[ $hook_name ] = new WP_Hook();
	}

	$wp_filter[ $hook_name ]->add_filter( $hook_name, $callback, $priority, $accepted_args );

	return true;
}

Changelog

VersionDescription
0.71Introduced.

User Contributed Notes

  1. Skip to note 8 content

    Example: Let’s add extra sections to TwentySeventeen Front page.
    By default, TwentySeventeen theme has 4 sections for the front page. This example will make them 6

    add_filter( 'twentyseventeen_front_page_sections', 'prefix_custom_front_page_sections' );
    	
    function prefix_custom_front_page_sections( $num_sections )
    {
    		return 6;
    }
  2. Skip to note 9 content

    To pass a variable to the called function of the filter, you can use closures (since PHP 5.3+) when the argument is not available in the original coded apply_filters. For example:

    add_filter('wp_footer', function($arguments) use ($myvar) { 
        return $myvar;
    }, $priority_integer, $accepted_arguments_integer);
  3. Skip to note 10 content

    Example: Let display custom length of post excerpt.

    if( ! function_exists( 'prefix_custom_excerpt_length' ) )
    {
    	function prefix_custom_excerpt_length( $length )
    	{
    		return 40;
    	}
    }
    add_filter( 'excerpt_length', 'prefix_custom_excerpt_length', 999 );

    By default, WordPress display 57 character. you can set custom length using above code. this time except length will be 40. it is a nice and easiest use of add_filter.

  4. Skip to note 11 content

    Example: If you want to inject a CLASS/ID CSS in content. Let’s add extra CLASS/ID to post content.

    //Add Class/ID to Post Content
    add_filter('the_content', 'xai_my_class');
    function xai_my_class($content)
    {
        //Replace the instance with the Class/ID markup.
        $string = '<ul'; //your tag
        $replace = '<ul class="detail-list"'; //add your class/id and tag
        $content = str_replace( $string, $replace, $content );
        return $content;
    }
  5. Skip to note 12 content

    In the special case you have to add a filter before WordPress starts, you can create and pre-populate the global $wp_filter array instead of using the not-yet available add_filter (or add_action) function:

    // Instead of add_filter( $tag, $function_to_add, $priority = 10, $accepted_args = 1 ):
    $GLOBALS['wp_filter'][ $tag ][ $priority ][] = array(
      'function'      => $function_to_add,
      'accepted_args' => $accepted_args
    );

    WP_Hook::build_preinitialized_hooks will automatically take care of the rest.
    Though to remove your filter, you can only use the remove_all_filters() function.

  6. Skip to note 13 content

    The Callback $function_to_add need not be defined until the Filter hook fires. This means that:

    1. The add_filter function does not check that $function_to_add exists
    2. The function statement for $function_to_add can be defined after the add_filter statement, even in a conditional (e.g. – if block) where the $function_to_add function does not actually exist until after the add_filter function executes
    3. If the Filter hook never fires, an undefined $function_to_add function will not be reported as an error

    Point 3 needs to be considered during Testing or Quality Control

    An undefined $function_to_add function detected when a Filter hook fires is reported as a Warning error:
    Warning: call_user_func_array() expects parameter 1 to be a valid callback, function 'reg_public1' not found or invalid function name in /var/www/example.com/public_html/wp-includes/class-wp-hook.php on line 288

  7. Skip to note 14 content

    Example
    The filter img_caption_shortcode is applied in media.php using the following call:

    // Allow plugins/themes to override the default caption template.
    $output = apply_filters( 'img_caption_shortcode', '', $attr, $content );
    if ( $output != '' )
    	return $output;

    The target filter function will be called with three arguments:

    ” <= This is normally the value the filter will be modifying
    $attr
    $content

    In order for the filter function to actually receive the full argument list, the call to add_filter() must be modified to specify there are 3 arguments on the parameter list.

    add_filter('img_caption_shortcode', 'my_img_caption_shortcode_filter',10,3);
    
    /**
     * Filter to replace the  shortcode text with HTML5 compliant code
     *
     * @return text HTML content describing embedded figure
     **/
    function my_img_caption_shortcode_filter($val, $attr, $content = null)
    {
    	extract( shortcode_atts( array(
    		'id'	=> '',
    		'align'	=> '',
    		'width'	=> '',
    		'caption' => ''
    	), $attr ) );
    	
    	if ( 1 > (int) $width || empty($caption) )
    		return $val;
    
    	$capid = '';
    	if ( $id ) {
    		$id = esc_attr( $id );
    		$capid = 'id="figcaption_' . $id . '" ';
    		$id = 'id="' . $id . '" aria-labelledby="figcaption_' . $id . '" ';
    	}
    
    	return '<figure ' . $id . 'class="wp-caption ' . esc_attr($align) . '" style="width: '
    	. (10 + (int) $width) . 'px">' . do_shortcode( $content ) . '<figcaption ' . $capid 
    	. 'class="wp-caption-text">' . $caption . '</figcaption></figure>';
    }

You must log in before being able to contribute a note or feedback.