apply_filters() WordPress Function

The apply_filters() function is used to filter data by passing it through a specified filter. This function is often used to filter data before it is displayed on a page or stored in a database.

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

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

Top ↑

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

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


Top ↑

Source

File: wp-includes/plugin.php

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

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


Top ↑

Changelog

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

The content displayed on this page has been created in part by processing WordPress source code files which are made available under the GPLv2 (or a later version) license by the Free Software Foundation. In addition to this, the content includes user-written examples and information. All material is subject to review and curation by the WPPaste.com community.