apply_filters( string $hook_name, mixed $value )

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


Description 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 );

Top ↑

Parameters Parameters

$hook_name

(string) (Required) The name of the filter hook.

$value

(mixed) (Required) The value to filter.

$args

(mixed) (Required) Additional parameters to pass to the callback functions.


Top ↑

Return Return

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


Top ↑

Source Source

File: wp-includes/plugin.php

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

	$args = func_get_args();

	// Do 'all' actions first.
	if ( isset( $wp_filter['all'] ) ) {
		$wp_current_filter[] = $hook_name;
		_wp_call_all_hook( $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;
	}

	// Don't pass the tag name to WP_Hook.
	array_shift( $args );

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

	array_pop( $wp_current_filter );

	return $filtered;
}


Top ↑

Changelog Changelog

Changelog
Version Description
0.71 Introduced.

Top ↑

User Contributed Notes User Contributed Notes

  1. Skip to note 1 content
    Contributed by Codex

    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 2 content
    Contributed by icc97

    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 3 content
    Contributed by peakwebsites

    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 4 content
    Contributed by tampadave

    Uh huh.

    apply_filters ( string $tag, mixed $value );

    function apply_filters( $tag, $value )

    Parameters:
    $tag — (string) (Required) The name of the filter hook.
    $value — (mixed) (Required) The value on which the filters hooked to $tag are applied on.
    $var — (mixed) (Required) Additional variables passed to the functions hooked to $tag.

    Right. Tip: this does not make sense, in case you missed it.

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