APPLY_FILTERS() │ WP 0.71

Функция apply_filters() вызовет все функции, которые подключены к определенному фильтру.

Эта функция запускает все функции, связанные с фильтром (hook_name). Вы можете создавать новые фильтры просто вызывая эту функцию и указывая название нового фильтра через параметр (hook_name).

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

Пример использования

// Функция обратного вызова для фильтра.
function example_callback( $string, $arg1, $arg2 ) {
    // (возможно) модифицируем $string.
    return $string;
}
add_filter( 'example_filter', 'example_callback', 10, 3 );

// Применение фильтров с вызовом функции 'example_callback()',
// которая подключена к 'example_filter' выше.
// 'example_filter' — это фильтр.
// 'filter me' — это значение, которое будет отфильтровано.
// $arg1 и $arg2 — дополнительные аргументы, передаваемые в функцию обратного вызова.
$value = apply_filters( 'example_filter', 'filter me', $arg1, $arg2 );

Что возвращает?

Функция возвращает отфильтрованное значение после применения всех подключенных функций.

Синтаксис

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

Параметры

• $hook_name (string) (обязательный) — название фильтра.
• $value (mixed) (обязательный) — значение, которое нужно отфильтровать.
• ...$args (mixed) (необязательный) — дополнительные параметры, которые передаются в функции обратного вызова.

Примеры

1. Получение отфильтрованного значения

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

2. Добавление функции фильтра (этот код нужно выполнить до вызова apply_filters()):

add_filter( 'filter_name', 'filter_function' );

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

3. Фильтрация значения и его отображение:

echo apply_filters( 'filter_name', $value );

4. Передача дополнительных аргументов в функцию фильтра:

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

// Добавляем функцию фильтра с дополнительными аргументами:
add_filter( 'filter_name', 'filter_function', 10, 3 );

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

5. Пример вывода отформатированного содержимого через фильтр:

Это альтернатива функции the_content():

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

Замечания

• Глобальные переменные. $wp_filter[] – хранит все фильтры и действия.
• Глобальные переменные. $wp_filters[] – хранит количество раз, когда каждый фильтр был вызван.
• Глобальные переменные. $wp_current_filter[] – хранит список текущих фильтров, где последний — это текущий.

Изменения

• С 0.71 — Введена функция.
• С 6.0.0 — Формализован существующий и уже задокументированный параметр ...$args, добавленный в сигнатуру функции.

Код функции apply_filters

Функция apply_filters() находится в файле 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 ];
    }

    // Сначала выполняем все действия.
    if ( isset( $wp_filter['all'] ) ) {
        $wp_current_filter[] = $hook_name;

        $all_args = func_get_args(); 
        _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;
    }

    // Передаем значение в WP_Hook.
    array_unshift( $args, $value );

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

    array_pop( $wp_current_filter );

    return $filtered;
}

Связанные функции

• add_filter() — добавляет функцию для обработки фильтра.
• current_filter() — возвращает имя текущего фильтра.
• doing_filter() — проверяет, выполняется ли фильтрация.
• has_filter() — проверяет, есть ли фильтр с указанным именем.
• remove_filter() — удаляет функцию фильтра.
• remove_all_filters() — удаляет все функции фильтров.