Использование apply_filters_ref_array() в WordPress: вызов фильтров с массивом аргументов

Функция apply_filters_ref_array() в WordPress позволяет применять фильтры, передавая аргументы в виде массива, и полезна, когда нужно передать аргументы по ссылке или когда их количество велико. Этот подход может быть удобен для передачи параметров, требующих манипуляций, без явного перечисления каждого аргумента.

apply_filters_ref_array( string $hook_name, array $args ): mixed

Параметры

• $hook_name — (строка, обязательный) Имя фильтра, который будет вызываться.
• $args — (массив, обязательный) Аргументы, передаваемые в массиве.

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

apply_filters_ref_array() возвращает значение, прошедшее через все функции, прикрепленные к указанному фильтру.

Пример 1: Основное применение с массивом аргументов

В этом примере фильтр apply_filters_ref_array() вызывается с массивом аргументов и работает аналогично apply_filters(), но передает значения из массива.

// Определяем массив аргументов
$args = array( 'text_value', false, 'sample', 42 );

// Применяем фильтр к массиву
$filtered_value = apply_filters_ref_array( 'example_filter', $args );

Эта запись аналогична вызову:

$filtered_value = apply_filters( 'example_filter', 'text_value', false, 'sample', 42 );

Пример 2: Добавление функции к фильтру и обработка нескольких параметров

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

// Добавляем фильтр, который будет работать с 3 аргументами
add_filter( 'example_filter', 'modify_values', 10, 3 );

function modify_values( $arg1, $arg2, $arg3 ) {
    // Объединяем значения аргументов
    return $arg1 . ' - ' . ( $arg2 ? 'true' : 'false' ) . ' - ' . $arg3;
}

// Вызываем фильтр
$result = apply_filters_ref_array( 'example_filter', array( 'Item', true, 123 ) );

// Результат: 'Item - true - 123'

Пример 3: Изменение переменных по ссылке

apply_filters_ref_array() позволяет передавать аргументы по ссылке, что делает ее полезной для изменения значений за пределами функции.

// Добавляем фильтр, изменяющий переданный по ссылке аргумент
add_filter( 'modify_by_reference', 'update_value', 10, 2 );

function update_value( $text, &$number ) {
    // Изменяем значение второго параметра
    $number *= 2;
    return strtoupper( $text );
}

// Исходные значения
$value = 10;
$text = apply_filters_ref_array( 'modify_by_reference', array( 'example', &$value ) );

// Результат: $text = 'EXAMPLE', $value = 20

Пример 4: Передача объекта через apply_filters_ref_array()

Так как объекты в PHP передаются по ссылке по умолчанию, их можно передавать через обычный apply_filters(). Однако apply_filters_ref_array() позволяет организовать передачу аргументов более гибко.

class SampleClass {
    public $property = 'initial';

    function __construct() {
        add_filter( 'modify_object', array( $this, 'modify_property' ), 10, 2 );
    }

    function modify_property( $status, $object ) {
        // Изменяем свойство объекта
        $object->property = 'modified';
        return $status;
    }
}

// Создаем экземпляр класса
$instance = new SampleClass();

// Вызываем фильтр с объектом в массиве аргументов
$status = apply_filters_ref_array( 'modify_object', array( 'active', $instance ) );

// Результат: $instance->property = 'modified'

Пример 5: Управление сложными параметрами с фильтром

Этот пример демонстрирует, как apply_filters_ref_array() может управлять сложными данными в фильтре, передавая многомерные массивы и изменяя их структуру.

// Добавляем фильтр, который модифицирует многомерный массив
add_filter( 'complex_filter', 'process_array', 10, 2 );

function process_array( $data, &$status ) {
    // Меняем статус по ссылке
    $status = 'completed';
    // Добавляем новый элемент в массив данных
    $data['additional'] = 'added';
    return $data;
}

// Инициализируем параметры
$status = 'pending';
$data = array( 'original' => 'value' );

// Применяем фильтр
$filtered_data = apply_filters_ref_array( 'complex_filter', array( $data, &$status ) );

// Результат: $filtered_data = array( 'original' => 'value', 'additional' => 'added' ), $status = 'completed'

Заключение

Функция apply_filters_ref_array() — мощный инструмент для работы с фильтрами, особенно когда параметры передаются в виде массивов. Она позволяет гибко управлять аргументами, включая передачу по ссылке, что открывает дополнительные возможности для изменения данных за пределами функции.