apply_filters() │ WP 0.71

Applies the attached PHP function to the specified filter.

The PHP function is attached to the filter using add_filter().

Used where it is necessary to change the value of a variable (for example, to allow changing the original text).

Used in plugins and themes to create hook-filters (hooks that allow changing the original data).

New filters must have unique names and must not coincide with existing filter names in WP.

In addition to filters, WP also has actions; their principle of operation is the same. The only difference is that a filter must return the received variable, i.e., it filters (changes) the data, while an action allows triggering a function or doing something else at the moment this action occurs. Actions are triggered by the function do_action()

See also the similar function apply_filters_ref_array(), which allows passing parameters by reference.

1 time — 0.000001 sec (speed of light) | 50000 times — 0.02 sec (speed of light) | PHP 7.0.32, WP 5.0.3

No Hooks.

Returns

Mixed. The filtered value $value, which is passed to the hook handler function.

Usage

apply_filters( $hook_name, $value, ...$args );

$hook_name(string) (required): The name of the filter.
$value(string/array/number/object/boolean) (required): The value that will be passed to the function as its first argument, in other words - the value that needs to be filtered.
...$args(string/array/number/object/boolean): Additional values that the filter will pass to the function.

Examples

#1 Usage examples

Obtaining a filtered value:

$value = apply_filters( 'filter_name', $value );

Add filter function (this code need to be executed before apply_filters() call):

add_filter( 'filter_name', 'filter_function' );

function filter_function( $value ){
	return $value;
}

Filter value and display it:

echo apply_filters( 'filter_name', $value );

Pass Additional Arguments for filter function:

$value = apply_filters( 'filter_name', $value, $arg1, $arg2, ... );

For example:

$value = apply_filters( 'filter_name', 'filter me', 'arg1', 'arg2 ');

Add filter function with additional arguments:

add_filter( 'filter_name', 'filter_function', 10, 3 );

function filter_function( $value, $arg1, $arg2 ){
	return $value;
}

#2 Example of outputting formatted content posts through a filter.

Alternative to the_content() function:

global $post;
echo apply_filters( 'the_content', $post->post_content );

Notes

Global. WP_Hook[]. $wp_filter Stores all of the filters and actions.
Global. Int[]. $wp_filters Stores the number of times each filter was triggered.
Global. String[]. $wp_current_filter Stores the list of current filters with the current one last.

Changelog

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

`apply_filters() apply filters` code ^{WP 6.8.1}

wp-includes/plugin.php

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;
}