apply_filters( string $tag, mixed $value )

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


Description Description

The callback functions attached to the filter hook are invoked by calling this function. This function can be used to create a new filter hook by simply calling this function with the name of the new hook specified using the $tag 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 Parameters

$tag

(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( $tag, $value ) {
	global $wp_filter, $wp_current_filter;

	$args = func_get_args();

	// Do 'all' actions first.
	if ( isset( $wp_filter['all'] ) ) {
		$wp_current_filter[] = $tag;
		_wp_call_all_hook( $args );
	}

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

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

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

	$filtered = $wp_filter[ $tag ]->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 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.