Функция ADD_FILTER() в WordPress: привязка функции к фильтру

# Функция ADD_FILTER() │ WP 0.71

Функция add_filter() позволяет привязывать указанную PHP-функцию к определённой метке фильтра. Когда фильтр срабатывает, значение обрабатывается этой функцией.

## Что такое фильтр?

Фильтр — это особая точка в коде, через которую вы можете "фильтровать" любые данные. Например, при получении и отображении текстовой информации из базы данных, вы можете изменить его на лету и показать уже изменённую версию. Благодаря фильтрам, вы можете вносить изменения, не редактируя основной код WordPress, а делая это в файле вашего плагина или темы.

WordPress предоставляет фильтры, позволяя плагинам изменять различные типы данных во время выполнения.

## Как работает add_filter()?

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

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

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

```php
function example_callback( $example ) {
    // Возможно, изменяем $example каким-то образом.
    return $example;
}
add_filter( 'example_filter', 'example_callback' );

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

Например, если вызов apply_filters() передаёт четыре аргумента, функции обратного вызова могут принимать как ни одного (то есть 1), так и до четырёх аргументов. Важно, чтобы количество принимаемых аргументов соответствовало тому, сколько аргументов функция на самом деле приняла. Если функция не принимает аргументы, это считается равным принятию одного аргумента.

Пример вызова фильтра

// Вызов фильтра.
$value = apply_filters( 'hook', $value, $arg2, $arg3 );

// Принятие 0/1 аргументов.
function example_callback() {
    ...
    return 'некоторое значение';
}
add_filter( 'hook', 'example_callback' ); // Приоритет по умолчанию 10, количество принимаемых аргументов по умолчанию 1.

// Принятие двух аргументов (три возможны).
function example_callback( $value, $arg2 ) {
    ...
    return $maybe_modified_value;
}
add_filter( 'hook', 'example_callback', 10, 2 ); // Приоритет 10, $accepted_args - 2.

Важные заметки

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

Синтаксис функции

add_filter( $hook_name, $callback, $priority, $accepted_args );

Параметры

• $hook_name (string) (обязательный) — имя фильтра, к которому вы добавляете обратный вызов.
• $callback (callable) (обязательный) — функция, которая будет выполняться при применении фильтра.
• $priority (int) — указывает порядок выполнения функций, связанных с определённым фильтром. Меньшие числа выполняются раньше. Функции с одинаковым приоритетом выполняются в порядке их добавления к фильтру. По умолчанию: 10.
• $accepted_args (int) — количество аргументов, принимаемых функцией. По умолчанию: 1.

Примеры использования add_filter()

Пример 1: Изменение подписи изображений

add_filter( 'img_caption_shortcode', 'my_img_caption_shortcode_filter', 10, 3 );
/**
 * Фильтр заменяет шорткод в соответствии со стандартами HTML5
 *
 * @return string HTML-код для описания тега 

 **/
function my_img_caption_shortcode_filter( $val, $attr, $content = null ){
    extract(shortcode_atts(array(
        'id'    => '',
        'align' => '',
        'width' => '',
        'caption' => ''
    ), $attr));

    if ( 1 > (int) $width || empty($caption) )
        return $val;

    $capid = '';
    if ( $id ) {
        $id = esc_attr($id);
        $capid = 'id="figcaption_'. $id . '" ';
        $id = 'id="' . $id . '" aria-labelledby="figcaption_' . $id . '" ';
    }

    return '
' . do_shortcode( $content ) . '
';
}

Пример 2: Анонимная функция

add_filter( 'the_title', function( $title ){
    return ''. $title. '';
});

Пример 3: Добавление текста в конец каждой статьи

add_filter( 'the_content', 'add_text_to_content' );
function add_text_to_content($content){
    $out = $content . "
При копировании статьи, пожалуйста, вставьте ссылку на источник!
";
    return $out;
}

Пример 4: Использование фильтров в классах

add_filter( 'media_upload_newtab', array( $this, 'media_upload_mycallback') );

Если метод статический, укажите имя класса:

add_filter( 'media_upload_newtab', array( 'My_Class', 'media_upload_mycallback') );

Заключение

Функция add_filter() ��вляется мощным инструментом для изменения и настройки данных в WordPress. Используйте её для создания уникальных и адаптированных функций на вашем сайте!

Примечание

Global. WP_Hook[]. $wp_filter — многомерный массив всех фильтров и привязанных к ним функций.