apply_filters( string $hook_name, mixed $value, mixed $args ): mixed

Calls the callback functions that have been added to a filter hook.

Description

This function invokes all functions attached to filter hook $hook_name.
It is possible to create new filter hooks by simply calling this function, specifying the name of the new hook using the $hook_name parameter.

The function also allows for multiple additional arguments to be passed to hooks.

Example usage:

// The filter callback function.
function example_callback( $string, $arg1, $arg2 ) {
    // (maybe) modify $string.
    return $string;
}
add_filter( 'example_filter', 'example_callback', 10, 3 );

/*
 * Apply the filters by calling the 'example_callback()' function
 * that's hooked onto `example_filter` above.
 *
 * - 'example_filter' is the filter hook.
 * - 'filter me' is the value being filtered.
 * - $arg1 and $arg2 are the additional arguments passed to the callback.
$value = apply_filters( 'example_filter', 'filter me', $arg1, $arg2 );

Parameters

$hook_namestringrequired
The name of the filter hook.
$valuemixedrequired
The value to filter.
$argsmixedoptional
Additional parameters to pass to the callback functions.

Return

mixed The filtered value after all hooked functions are applied to it.

Source

function apply_filters( $hook_name, $value, ...$args ) {
	global $wp_filter, $wp_filters, $wp_current_filter;

	if ( ! isset( $wp_filters[ $hook_name ] ) ) {
		$wp_filters[ $hook_name ] = 1;
	} else {
		++$wp_filters[ $hook_name ];
	}

	// Do 'all' actions first.
	if ( isset( $wp_filter['all'] ) ) {
		$wp_current_filter[] = $hook_name;

		$all_args = func_get_args(); // phpcs:ignore PHPCompatibility.FunctionUse.ArgumentFunctionsReportCurrentValue.NeedsInspection
		_wp_call_all_hook( $all_args );
	}

	if ( ! isset( $wp_filter[ $hook_name ] ) ) {
		if ( isset( $wp_filter['all'] ) ) {
			array_pop( $wp_current_filter );
		}

		return $value;
	}

	if ( ! isset( $wp_filter['all'] ) ) {
		$wp_current_filter[] = $hook_name;
	}

	// Pass the value to WP_Hook.
	array_unshift( $args, $value );

	$filtered = $wp_filter[ $hook_name ]->apply_filters( $value, $args );

	array_pop( $wp_current_filter );

	return $filtered;
}

Changelog

VersionDescription
6.0.0Formalized the existing and already documented ...$args parameter by adding it to the function signature.
0.71Introduced.

User Contributed Notes

  1. Skip to note 6 content

    Echo after Filtering

    echo apply_filters( $tag, $value );

    Get Filtered

    $myvar = apply_filters( $tag, $value );

    Additional Filter Arguments

    $myvar = apply_filters( $tag, $value, $param, $otherparam );

    For example:

    $myvar = apply_filters( 'example_filter', 'filter me', 'arg1', 'arg2 ');

    With the_title filter

    $my_custom_title = apply_filters('the_title', '  My Custom Title (tm)  ');
    $my_custom_title will now contain 'My Custom Title ™', since the_title filter applies wptexturize() and trim(), among others.
  2. Skip to note 7 content

    One fundamental argument that is easy to miss is specifying the number of arguments. Most filters have only one argument and so people drop the argument from add_filter.

    The 3, below is very important.

    add_filter( 'example_filter', 'example_callback', 10, 3 );

    Otherwise you get the following error, such as this StackOverflow question(http://stackoverflow.com/questions/24198086/missing-argument-2-for-the-function-in-wordpress):

    Missing argument 2 for example_callback()

  3. Skip to note 8 content

    Something that is not obvious from reading this function’s definition and description is that if add_filter( 'filter_name', 'filter_function' ) is never called/executed in code, the use of apply_filters( 'filter_name', $value ) will return the value of $value by default.

    I noticed a call to apply_filters( 'my_filter', ... ) in my theme’s functions.php file and couldn’t find a similar add_filter( 'my_filter', ... ) call anywhere else and was confused about this (I’m still wrapping my head around filters/hooks).

    More detail on this can be seen in the example found on this page: https://docs.presscustomizr.com/article/26-wordpress-actions-filters-and-hooks-a-guide-for-non-developers at the section about Filters.

  4. Skip to note 10 content

    If someone would like to give permission to other developers to change their plugin or theme function value without touching the core code then should use apply_filters

    For example –

    $value = 'Hello world!';
    echo apply_filters( 'wpdocs_hook_name', $value, $arg1, $arg2 ); // You can pass arguments also

    Now how 3rd party developer will work using this hook name? Using the add_filter developer can change the $value variable.
    Please follow below –

    function wpdocs_func_name( $value, $arg1, $arg2 ) {
    	return 'Hi Jack!'; 
    }
    add_filter( 'wpdocs_hook_name', 'wpdocs_func_name', 10, 3 ); // Must specify the arguments number if you use multiple arguments

    Now the result will show “Hi Jack!” instead of “Hello world!” and it has changed the $value variable dynamically without touching the core file.

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