add_filter() — описание функции WordPress на русском

Сигнатура

add_filter( string $hook_name, callable $callback, int $priority = 10, int $accepted_args = 1 ): true

Описание

WordPress предоставляет хуки-фильтры, позволяющие плагинам изменять различные типы внутренних данных во время выполнения.
Плагин может изменить данные, привязав функцию обратного вызова к хуку-фильтру. Когда фильтр впоследствии применяется, каждая привязанная функция обратного вызова запускается в порядке приоритета и получает возможность изменить значение, вернув новое.
В следующем примере показано, как функция обратного вызова привязывается к хуку-фильтру.
Обратите внимание, что $example передаётся в функцию обратного вызова, (возможно) изменяется и затем возвращается:
function example_callback( $example ) {
// При необходимости как-либо изменить $example.
return $example;
}
add_filter( 'example_filter', 'example_callback' );Привязанные функции обратного вызова могут принимать от нуля до полного числа аргументов, переданных как параметры в соответствующем вызове apply_filters().
Иными словами, если вызов apply_filters() передаёт всего четыре аргумента, привязанные к нему функции обратного вызова могут не принимать ни одного (то же самое, что 1) или принимать до четырёх. Важно, что значение $accepted_args должно отражать число аргументов, которое привязанная функция обратного вызова действительно решила принимать. Если функция обратного вызова не приняла ни одного аргумента, это считается тем же, что и приём 1 аргумента. Например:
// Вызов фильтра.
$value = apply_filters( 'hook', $value, $arg2, $arg3 );

// Приём нуля/одного аргумента.
function example_callback() {
...
return 'some value';
}
add_filter( 'hook', 'example_callback' ); // Где $priority равно значению по умолчанию 10, $accepted_args равно значению по умолчанию 1.

// Приём двух аргументов (возможны три).
function example_callback( $value, $arg2 ) {
...
return $maybe_modified_value;
}
add_filter( 'hook', 'example_callback', 10, 2 ); // Где $priority равно 10, $accepted_args равно 2._Примечание:_ Функция вернёт true независимо от того, является функция обратного вызова корректной или нет.
Забота об этом ложится на вас. Так сделано в целях оптимизации, чтобы всё работало максимально быстро.

Оригинал (английский)

WordPress offers filter hooks to allow plugins to modify various types of internal data at runtime.

A plugin can modify data by binding a callback to a filter hook. When the filter is later applied, each bound callback is run in order of priority, and given the opportunity to modify a value by returning a new value.

The following example shows how a callback function is bound to a filter hook.

Note that $example is passed to the callback, (maybe) modified, then returned:

function example_callback( $example ) {
    // Maybe modify $example in some way.
    return $example;
}
add_filter( 'example_filter', 'example_callback' );

Bound callbacks can accept from none to the total number of arguments passed as parameters in the corresponding apply_filters() call.

In other words, if an apply_filters() call passes four total arguments, callbacks bound to it can accept none (the same as 1) of the arguments or up to four. The important part is that the $accepted_args value must reflect the number of arguments the bound callback actually opted to accept. If no arguments were accepted by the callback that is considered to be the same as accepting 1 argument. For example:

// Filter call.
$value = apply_filters( 'hook', $value, $arg2, $arg3 );

// Accepting zero/one arguments.
function example_callback() {
    ...
    return 'some value';
}
add_filter( 'hook', 'example_callback' ); // Where $priority is default 10, $accepted_args is default 1.

// Accepting two arguments (three possible).
function example_callback( $value, $arg2 ) {
    ...
    return $maybe_modified_value;
}
add_filter( 'hook', 'example_callback', 10, 2 ); // Where $priority is 10, $accepted_args is 2.

_Note:_ The function will return true whether or not the callback is valid.
It is up to you to take care. This is done for optimization purposes, so everything is as quick as possible.

Параметры

$hook_name string обязательный

Имя фильтра, к которому добавляется функция обратного вызова.

$callback callable обязательный

Функция обратного вызова, которая будет запущена при применении фильтра.

$priority int необязательный = 10

Задаёт порядок, в котором выполняются функции, связанные с конкретным фильтром. Меньшие числа соответствуют более раннему выполнению, а функции с одинаковым приоритетом выполняются в том порядке, в котором были добавлены к фильтру.

$accepted_args int необязательный = 1

Число аргументов, которое принимает функция.

Возвращаемое значение

true

Исходный код

wp-includes/plugin.php:121

function add_filter( $hook_name, $callback, $priority = 10, $accepted_args = 1 ) {
	global $wp_filter;

	if ( ! isset( $wp_filter[ $hook_name ] ) ) {
		$wp_filter[ $hook_name ] = new WP_Hook();
	}

	$wp_filter[ $hook_name ]->add_filter( $hook_name, $callback, $priority, $accepted_args );

	return true;
}

История изменений

Версия	Описание
0.71	Introduced.