add_filter()
Прикріплює вказану PHP функцію до вказаного фільтра. Так, під час спрацьовування фільтра значення буде опрацьовано зазначеною PHP функцією.
Фільтри це, свого роду, зачіпки всередині коду, через які можна “відфільтрувати” будь-які дані. Наприклад, у період отримання та виведення тексту на екран із бази даних, можна “на льоту” змінити (відфільтрувати) цей текст і вивести на екран вже змінений варіант тексту. І завдяки фільтру для цього нам не доведеться редагувати функцію виведення у файлах движка, а можна підключитися до функції виведення через файл шаблону, використавши заздалегідь передбачений розробниками фільтр.
Функція не робить жодних перевірок: чи існує функція, що прикріплюється, чи передається назва функції у вигляді рядка і т.д.. Зроблено це, щоб add_filter() працювала максимально швидко.
Базовий список фільтрів весь список фільтрів
Про фільтри та події читайте у цій замітці: як працюють хуки у WordPress
add_action()
(дуже швидко) | 50000 разів – 0.05 сек
(швидкість світла) |
PHP 7.0.8, WP 4.7
Хуків немає.
Повертає
true.
Використання
add_filter( $tag, $function_to_add, $priority, $accepted_args );
-
$tag
(рядок) (обов’язковий) - Назва фільтра, для якого спрацьовуватиметься функція визначена у параметрі $function_to_add.
-
$function_to_add
(рядок) (обов’язковий) -
Назва функції, яка спрацьовуватиме для зазначеного в попередньому параметрі фільтра. Назва функції необхідно вказувати як рядка:
'название_функции'. Для функцій усередині класів вказуємо масив:
array('название_класса', 'название_функции'), Докладніше читаємо
тут (знання англ. Вітаються). -
$priority
(число) -
Пріоритет виконання функцій для одного і того ж фільтра. Чим більше число, тим пізніше буде виконуватися функція: наприклад, спочатку 10 потім 20. Функції з однаковим пріоритетом будуть виконуватися в порядку їхнього додавання до масиву фільтрів.
Типово: 10 -
$accepted_args
(число) -
Кількість аргументів, що передаються фільтром функції. Деякі фільтри можуть передавати більше ніж 1 аргумент, допустимо – 2, для таких випадків потрібно вказувати 2 у цьому параметрі.
За замовчуванням: 1
Приклади
#1 Усередині класів функцію фільтра потрібно вказувати через масив:
Перше значення масиву – це екземпляр класу, а друга назва методу цього класу.
add_filter( 'media_upload_newtab', array( $this, 'media_upload_mycallback') );
Якщо метод статичний, то першому значенні масиву потрібно вказати назву класу:
add_filter( 'media_upload_newtab', array( 'My_Class', 'media_upload_mycallback') );
#2 Звичайний приклад, що показує як можна додати будь-який напис наприкінці кожної статті, через фільтр the_content:
add_filter( 'the_content', 'add_text_to_content' );
function add_text_to_content($content){
$out = $content. "<p>При копіюванні статті, ставте зворотне посилання, будь ласка!</p>";
return $out;
}#3 Зміни блоку «підпис картинки» (сaption)
Приклад зміни підпису у картинок ( [сaption] ) під стандарти HTML 5. Функція змінює контент чіпляється на фільтр img_caption_shortcode, який відповідає за перетворення шоткоду [сaption] у контенті статті. Щоб отримати всі 3 параметри, що передаються фільтром, вкажемо аргумент $accepted_args – 3:
add_filter( 'img_caption_shortcode', 'my_img_caption_shortcode_filter', 10, 3);
/**
* Фільтр замінює шоткод [сaption] під стандарти HTML5
*
* @Повертає HTML текст описуючий тег figure
**/
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 '<figure'. $id. 'class="wp-caption ' . esc_attr($align) . '" style="width: '
. (10 + (int) $ width) . 'px">' . do_shortcode( $content ) . '<figcaption ' .
. 'class="wp-caption-text">' . $caption . '</figcaption></figure>';
}#4 Функцію можна передавати як анонімну:
Пам’ятайте, що неможливо видалити фільтр, оголошений анонімною функцією.
Не використовуйте анонімну функцію як коллбек функції, якщо мається на увазі багаторазове використання фільтра
add_filter( 'the_title', function( $title ){
return '<b>'. $title. '</b>';
});
нотатки
- Global. WP_Hook[]. $wp_filter A multidimensional array all hooks і callbacks hooked to them.
список змін
| З версії 0.71 | Введено. |
Код add_filter() add filter WP 6.0.2
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;
}