WordPress Hooks: Action vs Filter
Привіт:) WordPress Hooks дають змогу розширювати функціональність сайту без редагування ядра WordPress. За їх допомогою можна додавати власну логіку, змінювати вміст сторінок і налаштовувати поведінку тем та плагінів. У WordPress є два основні типи хуків — Action і Filter.
- WordPress Hooks: Action vs Filter — у чому різниця та як їх використовувати
- Що таке WordPress Hooks
- Як працює механізм хуків
- Action vs Filter: основна різниця
- Порівняльна таблиця Action і Filter
- Коли використовувати Action, а коли Filter
- Action Hooks у WordPress
-
Синтаксис
add_action() - Приклад 1. Виконання функції під час ініціалізації WordPress
- Приклад 2. Підключення CSS і JavaScript
- Приклад 3. Виконання коду після збереження запису
- Приклад 4. Використання анонімної функції
- Filter Hooks у WordPress
-
Синтаксис
add_filter() - Приклад 1. Зміна заголовка запису
- Приклад 2. Додавання тексту до вмісту публікації
- Приклад 3. Зміна параметрів запиту через Filter
- Приклад 4. Використання Filter з додатковими аргументами
-
do_action()таapply_filters(): чим відрізняються -
Як працює
do_action() -
Як працює
apply_filters() - Порівняння функцій
- Пріоритети хуків: як керувати порядком виконання
- Як пріоритет впливає на Filter
-
Параметр
accepted_args: скільки аргументів отримує callback - Як створювати власні Action і Filter Hooks
- Створення власного Action Hook
- Створення власного Filter Hook
- Як правильно називати власні хуки
- Як знайти потрібний Hook у WordPress
- 1. Використовуйте офіційну документацію
- 2. Перевіряйте вихідний код WordPress
- 3. Перевіряйте документацію стороннього плагіна
- Поширені помилки під час роботи з WordPress Hooks
- Помилка 1. Використання Action замість Filter
- Помилка 2. Відсутність return у Filter
- Помилка 3. Неправильна кількість аргументів
- Помилка 4. Надмірне використання глобальних змінних
- Помилка 5. Нескінченні цикли між хуками
- Помилка 6. Виведення HTML у Filter без потреби
- Помилка 7. Редагування файлів ядра або стороннього плагіна
- Помилка 8. Припущення, що callback виконується лише один раз
- Практичні рекомендації для розробників
- Action vs Filter у WordPress: короткий алгоритм вибору
- FAQ: поширені запитання про WordPress Hooks
- Що таке Hooks у WordPress простими словами?
- У чому головна різниця між Action і Filter?
- Чи можна використовувати add_action() для Filter Hook?
- Що станеться, якщо Filter не поверне значення?
- Що означає priority у WordPress Hooks?
- Для чого потрібен accepted_args?
- Чи можна створювати власні Hooks у WordPress?
- Де краще розміщувати власні хуки WordPress?
- Чи впливають хуки WordPress на продуктивність сайту?
- Як видалити зареєстрований Action або Filter?
- Чи можна зареєструвати декілька callback для одного хуку?
- Висновок
Розберімося, чим вони відрізняються, як працюють і коли використовувати кожен із них.

WordPress Hooks: Action vs Filter — у чому різниця та як їх використовувати
WordPress Hooks — один із ключових механізмів, завдяки яким можна змінювати поведінку WordPress без редагування файлів ядра. За допомогою хуків розробники додають власну функціональність, змінюють вміст сторінок, підключають скрипти, інтегрують сторонні сервіси та розширюють можливості тем і плагінів.
У WordPress існує два основних типи хуків: Action Hooks і Filter Hooks. Обидва дозволяють підключати власний PHP-код до певних етапів виконання системи, але використовуються для різних завдань.
Action запускає певну дію в потрібний момент, а Filter дає змогу змінити значення, яке WordPress використовуватиме далі. На практиці ця відмінність впливає на структуру коду, сумісність розширень і можливість підтримувати проєкт без зайвих труднощів.
У цьому матеріалі розглянемо, як працюють WordPress hooks, чим відрізняються Action і Filter, як правильно використовувати add_action() та add_filter(), що таке пріоритети й аргументи хуків, а також як створювати власні точки розширення для тем і плагінів.
Що таке WordPress Hooks
WordPress Hooks — це механізм розширення системи, який дозволяє виконувати власний код у визначених точках життєвого циклу WordPress або змінювати дані під час їх обробки.
Уявімо, що потрібно додати повідомлення після публікації статті. Можна змінити файл ядра WordPress і вставити туди потрібний код. Проте після оновлення системи ці зміни можуть зникнути. Крім того, редагування ядра ускладнює підтримку сайту та створює ризик конфліктів.
Hooks вирішують цю проблему іншим способом. WordPress надає точки, до яких можна під'єднати власні функції. Коли виконання доходить до відповідної точки, система запускає зареєстровані обробники або передає значення функціям, які можуть його змінити.
Наприклад, розробник може:
- додати код під час ініціалізації WordPress;
- підключити CSS-файл або JavaScript;
- виконати дію після збереження запису;
- змінити заголовок або вміст публікації;
- додати власні поля до адміністративної панелі;
- змінити параметри запиту до бази даних;
- розширити функціональність WooCommerce або іншого плагіна, якщо він надає відповідні хуки;
- створити точки розширення у власному плагіні.
Hooks широко використовуються в ядрі WordPress, темах і плагінах. Саме завдяки їм різні компоненти можуть взаємодіяти, не змінюючи безпосередньо вихідний код один одного.
Як працює механізм хуків
У типовому сценарії взаємодія складається з трьох елементів:
- Hook — назва точки розширення, наприклад
initабоthe_content. - Callback — функція або інший викликуваний PHP-об'єкт, який потрібно виконати.
- Реєстрація — підключення callback до відповідного хуку за допомогою
add_action()абоadd_filter().
Для Action у ядрі або іншому компоненті викликається do_action(). Для Filter використовується apply_filters().
Розглянемо простий приклад:
function mysite_register_custom_feature() {
// Реєстрація або ініціалізація функціональності.
}
add_action(
'init',
'mysite_register_custom_feature'
);
У цьому випадку функція mysite_register_custom_feature() буде виконана під час спрацювання хука init.
Зверніть увагу: add_action() не запускає функцію відразу. Він реєструє callback, який WordPress виконає пізніше, коли відповідний Action буде викликаний.
Докладніше про механізм можна прочитати в офіційній документації WordPress Plugin Handbook: Hooks.

Action vs Filter: основна різниця
Найпростіший спосіб відрізнити два типи хуків — визначити, чи потрібно виконати певну операцію, чи змінити значення, яке використовується далі.
Action виконує завдання. Filter змінює дані та повертає результат.
Наприклад, надсилання повідомлення після створення замовлення — це завдання для Action. Зміна тексту повідомлення перед його відображенням — завдання для Filter.
Порівняльна таблиця Action і Filter
| Критерій | Action Hook | Filter Hook |
|---|---|---|
| Основне призначення | Виконати певну операцію | Змінити передане значення |
| Реєстрація callback | add_action() | add_filter() |
| Виклик хуку | do_action() | apply_filters() |
| Типовий результат callback | Операція без повернення значення для хуку | Повернення обробленого значення |
| Повернення результату хуку | do_action() не повертає результат callback | apply_filters() повертає підсумкове значення |
| Робота з даними | Може отримувати аргументи для виконання завдання | Отримує значення та повертає його модифіковану версію |
| Типові сценарії | Реєстрація компонентів, надсилання сповіщень, виконання операцій | Зміна заголовків, тексту, аргументів запиту або налаштувань |
| Декілька callback | Можна зареєструвати декілька обробників | Можна послідовно застосувати декілька модифікацій |
| Повернення значення з callback | Не використовується як результат Action | Використовується як наступне значення Filter |

Важливо розуміти, що Action теж може отримувати аргументи, зокрема об'єкти, ідентифікатори або масиви даних. Проте його callback не повинен повертати значення для подальшої обробки самим Action.
У Filter головним є значення, яке передається через ланцюжок обробників. Якщо callback не поверне правильний результат, наступні етапи отримають некоректні дані.
Коли використовувати Action, а коли Filter
Користуйтеся Action, якщо потрібно:
- виконати код у певний момент;
- зареєструвати власну функціональність;
- надіслати сповіщення;
- створити запис у журналі подій;
- виконати додаткову операцію після збереження даних;
- вивести додатковий HTML у передбаченій для цього точці.
Користуйтеся Filter, якщо потрібно:
- змінити текст або HTML;
- модифікувати масив аргументів;
- змінити значення налаштування;
- скоригувати параметри запиту;
- перетворити значення перед його використанням;
- надати іншим розробникам можливість змінювати результат роботи вашого коду.
Є й просте практичне правило: якщо завдання можна описати словами "зробити щось, коли відбувається подія", найімовірніше, потрібен Action. Якщо воно звучить як "отримати значення, змінити його та повернути", потрібен Filter.
Action Hooks у WordPress
Action Hooks дозволяють під'єднати функцію до певної точки виконання WordPress. Коли ця точка спрацьовує, система запускає зареєстровані callback-функції.
Для реєстрації використовується add_action().
Синтаксис add_action()
add_action(
$hook_name,
$callback,
$priority,
$accepted_args
);
Параметри:
$hook_name— назва Action Hook, до якого потрібно під'єднати функцію.$callback— функція або інший викликуваний PHP-об'єкт.$priority— пріоритет виконання. За замовчуванням дорівнює10.$accepted_args— кількість аргументів, які WordPress передасть callback-функції. За замовчуванням дорівнює1.
Останні два параметри необов'язкові. Проте під час роботи зі складнішими хуками їх важливо розуміти.
Приклад 1. Виконання функції під час ініціалізації WordPress
Припустімо, потрібно виконати певну підготовчу операцію під час спрацювання init.
function mysite_initialize_feature() {
// Тут виконується необхідна ініціалізація.
}
add_action(
'init',
'mysite_initialize_feature'
);
Після реєстрації WordPress викличе mysite_initialize_feature() під час виконання хука init.
Такий підхід використовують, наприклад, для реєстрації власних типів записів, таксономій і rewrite rules. Конкретна реалізація залежить від завдання та моменту, коли відповідні API WordPress доступні.
Приклад 2. Підключення CSS і JavaScript
Для підключення стилів і скриптів WordPress передбачає спеціальний Action Hook wp_enqueue_scripts.
function mysite_enqueue_assets() {
wp_enqueue_style(
'mysite-style',
get_stylesheet_uri(),
array(),
'1.0.0'
);
}
add_action(
'wp_enqueue_scripts',
'mysite_enqueue_assets'
);
Цей приклад підключає основний файл стилів активної таблиці стилів теми.
Для окремих CSS- і JavaScript-файлів можна використовувати wp_enqueue_style() та wp_enqueue_script() відповідно. Для адміністративної панелі існують окремі хуки, тому важливо обирати точку розширення відповідно до місця використання ресурсів.
Перевага такого підходу — WordPress може коректно керувати залежностями, версіями та порядком підключення ресурсів.
Приклад 3. Виконання коду після збереження запису
WordPress має Action Hook save_post, який можна використовувати для реагування на збереження запису.
function mysite_log_post_save(
$post_id,
$post,
$update
) {
if ( wp_is_post_revision( $post_id ) ) {
return;
}
if ( wp_is_post_autosave( $post_id ) ) {
return;
}
// Тут можна виконати потрібну операцію.
}
add_action(
'save_post',
'mysite_log_post_save',
10,
3
);
У цьому прикладі callback отримує три аргументи:
$post_id— ідентифікатор запису;$post— об'єкт запису;$update— ознаку того, чи оновлюється наявний запис.
Зверніть увагу на останній параметр add_action(): значення 3 означає, що callback має отримати три аргументи.
Цей приклад показує лише базову структуру обробника. Якщо код змінює метадані, виконує зовнішні запити або запускає інші операції зі збереженням даних, потрібно окремо врахувати права користувача, повторні виклики, автозбереження та можливі цикли.
Приклад 4. Використання анонімної функції
Callback не обов'язково має бути окремою іменованою функцією. Для невеликої операції можна використати анонімну функцію.
add_action(
'init',
function () {
// Виконання невеликої операції.
}
);
Цей спосіб зручний, коли логіка коротка та не потребує повторного використання.
Проте для складних обробників і сценаріїв, де потрібне видалення callback, краще використовувати іменовані функції або методи класів. Анонімні функції складніше повторно передати до remove_action(), якщо їхній об'єкт не збережений у змінній.
Filter Hooks у WordPress
Filter Hooks призначені для зміни даних, які WordPress використовує під час виконання певної операції.
На відміну від Action, Filter передає результат одного обробника наступному. Після завершення ланцюжка WordPress отримує остаточне значення та використовує його далі.
Для реєстрації застосовується add_filter().
Синтаксис add_filter()
add_filter(
$hook_name,
$callback,
$priority,
$accepted_args
);
Параметри мають таке саме призначення, як у add_action():
$hook_name— назва Filter Hook;$callback— функція для обробки даних;$priority— порядок виконання callback;$accepted_args— кількість аргументів, які потрібно передати функції.
Головна вимога до Filter — callback повинен повертати значення, яке має використовуватися далі.
Приклад 1. Зміна заголовка запису
Припустімо, потрібно додати префікс до заголовків публікацій.
function mysite_modify_post_title( $title ) {
return 'Матеріал: ' . $title;
}
add_filter(
'the_title',
'mysite_modify_post_title'
);
Якщо заголовок має значення Налаштування WordPress, після застосування фільтра результатом стане Матеріал: Налаштування WordPress.
Функція не змінює заголовок безпосередньо в базі даних. Вона змінює значення, яке проходить через конкретний фільтр. Реальний результат залежить від того, де й коли WordPress застосовує the_title, а також від інших зареєстрованих обробників.
Це важлива відмінність: фільтрація значення під час виведення не тотожна зміні збережених даних.
Приклад 2. Додавання тексту до вмісту публікації
Один із поширених сценаріїв — додавання примітки до вмісту запису.
function mysite_append_post_note( $content ) {
if ( ! is_singular( 'post' ) || ! is_main_query() ) {
return $content;
}
if ( ! in_the_loop() ) {
return $content;
}
$note = '<p class="mysite-post-note">';
$note .= 'Дякуємо за прочитання матеріалу!';
$note .= '</p>';
return $content . $note;
}
add_filter(
'the_content',
'mysite_append_post_note'
);
Тут фільтр the_content отримує вміст публікації, після чого функція додає до нього HTML-фрагмент.
Перевірки обмежують застосування примітки основним циклом для одиничного запису типу post. Це допомагає уникнути небажаних змін у списках, віджетах та інших контекстах.
Однак навіть такий код потрібно перевіряти в конкретній темі. Фільтр вмісту може застосовуватися повторно або в різних контекстах. Якщо потрібно гарантовано уникнути повторного додавання елемента, варто передбачити додатковий захист відповідно до сценарію.
Приклад 3. Зміна параметрів запиту через Filter
Фільтри можуть працювати не лише з текстом. Наприклад, через pre_get_posts можна змінити параметри основного запиту до публікацій.
function mysite_adjust_archive_query( $query ) {
if ( is_admin() || ! $query->is_main_query() ) {
return;
}
if ( $query->is_home() ) {
$query->set( 'posts_per_page', 12 );
}
}
add_action(
'pre_get_posts',
'mysite_adjust_archive_query'
);
Цей приклад навмисно демонструє важливий нюанс: попри те, що ми змінюємо дані об'єкта запиту, pre_get_posts є Action Hook, а не Filter Hook.
Чому? Тому що його призначення — дозволити виконати операцію над об'єктом запиту в певний момент. Callback змінює властивості об'єкта за допомогою методу set(), але не повертає нове значення для ланцюжка фільтрації.
Отже, не варто визначати тип хуку лише за тим, чи змінює він дані. Важливо розуміти, як саме організована його робота.
Приклад 4. Використання Filter з додатковими аргументами
Фільтр може отримувати початкове значення та додаткові параметри.
function mysite_modify_price(
$price,
$product_id,
$currency
) {
// $product_id і $currency надають контекст.
return $price;
}
add_filter(
'mysite_product_price',
'mysite_modify_price',
10,
3
);
У цьому випадку callback очікує три аргументи. Перший — значення, яке можна модифікувати. Другий і третій — додатковий контекст.
Щоб приклад працював, у коді, який створює відповідний власний фільтр, потрібно передати всі ці аргументи через apply_filters().
$price = apply_filters(
'mysite_product_price',
$price,
$product_id,
$currency
);
Після виконання apply_filters() змінене значення потрібно використати або зберегти. Якщо результат проігнорувати, модифікації не вплинуть на подальшу роботу програми.
do_action() та apply_filters(): чим відрізняються
add_action() і add_filter() використовують для реєстрації callback-функцій. Натомість do_action() та apply_filters() викликають відповідні хуки в коді.
Ці пари функцій виконують різні завдання.
Як працює do_action()
Функція do_action() запускає всі callback, зареєстровані для певного Action Hook.
do_action(
'mysite_after_report_created',
$report_id
);
Цей виклик повідомляє WordPress, що настала відповідна точка виконання. Якщо до хуку під'єднано обробники, вони будуть виконані в порядку своїх пріоритетів.
Наприклад, різні компоненти можуть реагувати на створення звіту:
function mysite_log_report( $report_id ) {
// Записати інформацію про звіт у журнал.
}
function mysite_notify_report_created( $report_id ) {
// Запустити передбачене сповіщення.
}
add_action(
'mysite_after_report_created',
'mysite_log_report',
10,
1
);
add_action(
'mysite_after_report_created',
'mysite_notify_report_created',
20,
1
);
Обидві функції можуть реагувати на одну подію, не знаючи про внутрішню реалізацію одна одної.
do_action() не повертає результат цих callback. Його роль — запустити зареєстровані обробники.
Як працює apply_filters()
Функція apply_filters() передає значення зареєстрованим callback і повертає остаточний результат обробки.
$label = apply_filters(
'mysite_report_label',
'Звіт'
);
Якщо до фільтра не під'єднано жодного callback, функція поверне початкове значення.
Приклад із модифікацією:
function mysite_prefix_report_label( $label ) {
return 'Документ: ' . $label;
}
add_filter(
'mysite_report_label',
'mysite_prefix_report_label'
);
$label = apply_filters(
'mysite_report_label',
'Звіт'
);
// Результат: Документ: Звіт
У цьому випадку результат фільтра потрібно присвоїти змінній або передати іншій функції. Сам по собі виклик apply_filters() не гарантує, що змінене значення буде використане в потрібному місці.
Порівняння функцій
| Функція | Призначення | Що відбувається з результатом |
|---|---|---|
add_action() | Реєструє callback для Action | Функція буде виконана під час спрацювання хуку |
do_action() | Викликає Action Hook | Повернення callback не стає результатом хуку |
add_filter() | Реєструє callback для Filter | Функція бере участь у зміні значення |
apply_filters() | Застосовує Filter Hook | Повертає остаточне оброблене значення |
Пріоритети хуків: як керувати порядком виконання
До одного хуку можна під'єднати декілька callback. WordPress використовує параметр priority, щоб визначити, у якому порядку їх потрібно виконувати.
За замовчуванням пріоритет дорівнює 10.
Правило просте: менше число означає раніше виконання. Якщо декілька callback мають однаковий пріоритет, вони виконуються в порядку реєстрації.
Наприклад:
function mysite_first_callback() {
// Виконається раніше.
}
function mysite_second_callback() {
// Виконається пізніше.
}
add_action(
'init',
'mysite_second_callback',
20
);
add_action(
'init',
'mysite_first_callback',
5
);
Попри те, що mysite_second_callback() зареєстровано раніше, mysite_first_callback() виконається першою через нижчий пріоритет.
Як пріоритет впливає на Filter
Для Filter принцип той самий, але порядок може змінити кінцеве значення.
function mysite_add_prefix( $value ) {
return 'Префікс: ' . $value;
}
function mysite_add_suffix( $value ) {
return $value . ' — готово';
}
add_filter(
'mysite_label',
'mysite_add_prefix',
10
);
add_filter(
'mysite_label',
'mysite_add_suffix',
20
);
$label = apply_filters(
'mysite_label',
'Матеріал'
);
Підсумкове значення буде таким:
Префікс: Матеріал — готово
Спочатку спрацює mysite_add_prefix(), а потім mysite_add_suffix(). Кожен callback отримує результат попереднього.
Якщо змінити порядок виконання, результат може бути іншим. Особливо це важливо, коли фільтри додають HTML, змінюють форматування або працюють із масивами.
Не варто встановлювати незвичні пріоритети без потреби. Використовуйте їх тоді, коли порядок справді має значення, і перевіряйте взаємодію з іншими розширеннями.

Параметр accepted_args: скільки аргументів отримує callback
Одна з поширених причин помилок під час роботи з WordPress Hooks — неправильна кількість аргументів.
Розглянемо приклад:
function mysite_post_callback(
$post_id,
$post,
$update
) {
// Обробка запису.
}
add_action(
'save_post',
'mysite_post_callback',
10,
3
);
Останнє значення 3 повідомляє WordPress, що callback потрібно передати три аргументи.
Якщо не вказати цей параметр, WordPress використовуватиме значення за замовчуванням — 1. У результаті функція може не отримати всі дані, яких очікує.
Водночас не можна механічно копіювати кількість аргументів з іншого хуку. Для кожного Action або Filter потрібно перевіряти офіційну документацію, адже різні хуки передають різні набори параметрів.
Варто враховувати й те, що $accepted_args визначає максимальну кількість аргументів, які WordPress передасть callback, а не змушує функцію використовувати їх усі.
Для Filter є додаткове правило: перший аргумент зазвичай містить значення, яке потрібно змінити. Інші аргументи надають контекст і не замінюють основного значення, яке повертається через return.
Як створювати власні Action і Filter Hooks
Якщо ви розробляєте власний плагін або тему, можна не лише використовувати наявні хуки WordPress, а й створювати власні точки розширення.
Це особливо корисно для плагінів, які мають підтримувати сторонні інтеграції або дозволяти іншим розробникам адаптувати функціональність без редагування вихідного коду.
Створення власного Action Hook
Припустімо, плагін формує звіт і після завершення цього процесу має надати іншим компонентам можливість виконати додаткові операції.
function mysite_generate_report() {
$report_id = 123;
// Основна логіка створення звіту.
do_action(
'mysite_after_report_created',
$report_id
);
}
Інший розробник може під'єднати власний callback:
function mysite_handle_new_report( $report_id ) {
// Виконати додаткову операцію.
}
add_action(
'mysite_after_report_created',
'mysite_handle_new_report',
10,
1
);
Тепер сторонній код може реагувати на завершення створення звіту, не змінюючи основну функцію плагіна.
Зверніть увагу: значення $report_id у прикладі умовне. У реальному коді потрібно передавати фактичний ідентифікатор створеного об'єкта.
Створення власного Filter Hook
Якщо потрібно дозволити змінювати значення, використовуйте apply_filters().
function mysite_get_report_label() {
$label = 'Звіт користувача';
return apply_filters(
'mysite_report_label',
$label
);
}
Інший компонент може змінити результат:
function mysite_customize_report_label( $label ) {
return 'Мій проєкт: ' . $label;
}
add_filter(
'mysite_report_label',
'mysite_customize_report_label'
);
Тепер функція mysite_get_report_label() поверне змінене значення.
Важливо, що фільтр застосовано саме до значення, яке повертається. Якби результат apply_filters() не використовувався, сторонній callback міг би виконатися, але його модифікація не вплинула б на значення, яке повертає функція.

Як правильно називати власні хуки
Назви хуків мають бути зрозумілими, стабільними та достатньо унікальними.
Рекомендації:
- використовуйте префікс назви плагіна або унікальний ідентифікатор проєкту;
- для Action обирайте назви, які описують подію або дію;
- для Filter використовуйте назви, що вказують на значення, яке можна змінити;
- документуйте аргументи, їхні типи та момент виклику;
- не змінюйте назву або структуру аргументів без урахування зворотної сумісності.
Наприклад, mysite_after_order_created краще за загальне after_created, оскільки перша назва з меншою ймовірністю конфліктуватиме з хуком іншого плагіна.
Як знайти потрібний Hook у WordPress
У реальному проєкті часто виникає запитання: який саме хук потрібно використати для конкретного завдання?
Наприклад, необхідно додати елемент до адміністративної панелі, змінити вміст публікації або виконати операцію після оновлення налаштувань.
Найнадійніший підхід — починати з документації та визначення точки, у якій WordPress виконує потрібну операцію.
1. Використовуйте офіційну документацію
У WordPress Developer Resources можна знайти опис функцій, Action Hooks і Filter Hooks, їхні аргументи та приклади використання.
Особливо важливо перевіряти:
- момент спрацювання хуку;
- список аргументів;
- типи переданих значень;
- контекст виконання;
- можливість використання хуку в адміністративній панелі або на фронтенді.
Назва хуку не завжди повністю пояснює його поведінку, тому документація має вирішальне значення.
2. Перевіряйте вихідний код WordPress
Якщо опису недостатньо, можна знайти місце виклику do_action() або apply_filters() у вихідному коді.
Наприклад, якщо ви шукаєте, де змінюється певне значення, знайдіть відповідний виклик apply_filters() і перевірте, яке значення передається та як використовується результат.
Для Action аналогічно шукайте do_action().
Це допомагає зрозуміти не лише назву хуку, а й точний момент, коли він спрацьовує.
3. Перевіряйте документацію стороннього плагіна
Якщо потрібно змінити поведінку WooCommerce, конструктора сторінок або іншого розширення, не варто автоматично припускати, що відповідний хук належить ядру WordPress.
Плагіни часто створюють власні хуки. Їхня доступність і поведінка можуть залежати від версії розширення.
Використовуйте документацію конкретного плагіна, його вихідний код і changelog. Особливо уважно перевіряйте хуки, які використовуються для роботи з оплатами, замовленнями, доступом до даних або іншими критичними процесами.

Поширені помилки під час роботи з WordPress Hooks
Навіть досвідчені розробники можуть зіткнутися з проблемами, якщо неправильно вибирають хук, не враховують аргументи або порушують принципи роботи Filter.
Помилка 1. Використання Action замість Filter
Припустімо, потрібно змінити заголовок публікації. Якщо зареєструвати callback через add_action() на хуку, призначеному для фільтрації заголовка, це не дасть очікуваного результату.
Для зміни значення потрібно використовувати відповідний Filter Hook.
Водночас не всі хуки, що змінюють дані, є фільтрами. Наприклад, pre_get_posts — це Action, хоча через нього можна змінювати об'єкт запиту.
Тому тип хуку слід визначати за його реалізацією та призначенням, а не лише за назвою.
Помилка 2. Відсутність return у Filter
Неправильно:
function mysite_modify_title( $title ) {
$title = 'Новий заголовок';
}
У цьому прикладі функція не повертає змінене значення. PHP поверне null, тому ланцюжок фільтрації може отримати некоректний результат.
Правильно:
function mysite_modify_title( $title ) {
return 'Новий заголовок';
}
А якщо потрібно доповнити початкове значення:
function mysite_modify_title( $title ) {
return $title . ' — оновлено';
}
У Filter потрібно повертати значення, яке має використовуватися далі. Якщо зміна не потрібна, повертайте початковий аргумент.
Помилка 3. Неправильна кількість аргументів
Якщо callback очікує три параметри, але зареєстрований із $accepted_args = 1, функція не отримає повний набір аргументів.
Це може призвести до попереджень, помилок або некоректної логіки.
Перед використанням хуку перевіряйте його сигнатуру та передавайте правильне значення $accepted_args.
Помилка 4. Надмірне використання глобальних змінних
Глобальні змінні можуть здаватися швидким способом передавання даних між функціями, але вони ускладнюють розуміння коду та створюють приховані залежності.
Якщо потрібне значення можна передати через аргументи власного хуку або отримати через відповідний API WordPress, зазвичай це кращий підхід.
Помилка 5. Нескінченні цикли між хуками
Небезпечно створювати логіку, у якій callback запускає той самий хук повторно або спричиняє повторний виклик функції, яка його активує.
Наприклад, якщо під час обробки save_post функція знову оновлює той самий запис, це може спричинити повторне спрацювання хуку.
У таких випадках потрібно перевіряти контекст виконання, відокремлювати операції читання від запису та передбачати захист від повторного входу, якщо він справді потрібен.
Помилка 6. Виведення HTML у Filter без потреби
Filter призначений для зміни значення, а не для побічних ефектів на кшталт безпосереднього виведення вмісту.
Якщо потрібно додати HTML у відповідну точку шаблону, часто краще використати Action, передбачений для цього завдання.
Якщо ж потрібно змінити HTML-рядок, який уже проходить через фільтр, повертайте змінений рядок.
Помилка 7. Редагування файлів ядра або стороннього плагіна
Прямі зміни файлів WordPress Core або плагіна можуть зникнути після оновлення. Крім того, вони ускладнюють підтримку та створюють проблеми під час перенесення проєкту.
Якщо доступний відповідний хук, використовуйте його. Для власної логіки зазвичай підійдуть окремий плагін, mu-plugin або дочірня тема — залежно від призначення коду.
Помилка 8. Припущення, що callback виконується лише один раз
Деякі хуки можуть спрацьовувати багаторазово протягом одного запиту. Також один і той самий callback може бути зареєстрований кілька разів або виконуватися в різних контекстах.
Якщо функція створює записи, надсилає повідомлення чи виконує інші операції, важливо враховувати можливість повторного виклику.
Не варто покладатися на припущення про одноразове виконання, якщо це не гарантовано логікою конкретного сценарію.
Практичні рекомендації для розробників
Щоб WordPress Hooks залишалися зручним інструментом розширення, дотримуйтеся кількох принципів.
Використовуйте хуки за призначенням. Action має запускати операцію, а Filter — повертати змінене значення.
Не змінюйте ядро WordPress. Виносьте власну логіку в плагін, mu-plugin або дочірню тему, якщо зміни стосуються оформлення.
Перевіряйте аргументи. Не всі хуки передають однакову кількість параметрів або однакові типи даних.
Застосовуйте пріоритети обґрунтовано. Значення, відмінні від стандартного 10, потрібні тоді, коли важливий порядок виконання.
Повертайте коректне значення з Filter. Воно має відповідати очікуванням коду, який використовує результат.
Уникайте зайвих побічних ефектів. Особливо це стосується фільтрів, які можуть застосовуватися в різних контекстах.
Документуйте власні хуки. Вказуйте призначення, момент виклику, аргументи та очікуваний формат значень.
Думайте про зворотну сумісність. Якщо інші розробники використовують ваші хуки, зміна їхньої поведінки може вплинути на сторонні розширення.
Перевіряйте код на тестовому середовищі. Це особливо важливо для хуків, пов'язаних зі збереженням даних, автентифікацією, платежами та обробкою замовлень.
Action vs Filter у WordPress: короткий алгоритм вибору
Якщо ви не впевнені, який хук потрібен, дайте відповідь на три запитання.
- Чи потрібно виконати певну операцію в конкретний момент? Якщо так, перевірте відповідні Action Hooks.
- Чи потрібно змінити значення, яке WordPress використовуватиме далі? Якщо так, шукайте відповідний Filter Hook.
- Чи справді обраний хук викликається в потрібному контексті та передає необхідні аргументи? Перевірте документацію або вихідний код.
Наприклад:
| Завдання | Типовий підхід |
|---|---|
| Підключити CSS-файл теми | Action: wp_enqueue_scripts |
| Реагувати на збереження запису | Action: save_post |
| Змінити заголовок публікації | Filter: the_title |
| Доповнити вміст запису | Filter: the_content |
| Змінити параметри основного запиту | Action: pre_get_posts |
| Дозволити стороннім розширенням змінювати власне текстове значення | Власний Filter через apply_filters() |
| Повідомити сторонні розширення про завершення операції | Власний Action через do_action() |
Ця таблиця описує типові сценарії. Перед реалізацією потрібно перевірити поведінку конкретного хуку, оскільки деякі з них мають додаткові умови або обмеження.
FAQ: поширені запитання про WordPress Hooks
Що таке Hooks у WordPress простими словами?
Hooks — це точки розширення, через які можна під'єднати власний код до WordPress. Вони дозволяють реагувати на певні події або змінювати дані без прямого редагування ядра системи.
У чому головна різниця між Action і Filter?
Action запускає певну операцію, а Filter змінює значення та повертає його для подальшого використання. Для реєстрації Action застосовують add_action(), а для Filter — add_filter().
Чи можна використовувати add_action() для Filter Hook?
Технічно WordPress дозволяє зареєструвати callback через add_action() або add_filter() для одного й того самого імені хуку, оскільки обидві функції використовують спільний механізм реєстрації. Проте це не означає, що їх варто довільно підміняти.
Для Filter потрібно повертати значення, а для Action — виконувати операцію без розрахунку на повернення результату. Використовуйте функцію, яка відповідає призначенню хуку, щоб код залишався зрозумілим і передбачуваним.
Що станеться, якщо Filter не поверне значення?
Якщо callback не виконує return, PHP поверне null. Це значення може замінити попередній результат у ланцюжку фільтрації та спричинити помилки в коді, який очікує рядок, масив, число або об'єкт.
Якщо змінювати значення не потрібно, повертайте початковий аргумент.
Що означає priority у WordPress Hooks?
priority визначає порядок виконання callback. Стандартне значення — 10. Менше число означає раніше виконання, а за однакового пріоритету callback запускаються в порядку реєстрації.
Для чого потрібен accepted_args?
accepted_args визначає максимальну кількість аргументів, які WordPress передасть callback. Його потрібно узгоджувати з параметрами функції та аргументами, які передає відповідний хук.
Чи можна створювати власні Hooks у WordPress?
Так. Для створення власного Action використовують do_action(), а для Filter — apply_filters(). Інші компоненти можуть під'єднувати до них callback через add_action() або add_filter().
Де краще розміщувати власні хуки WordPress?
Для функціональності, яка має працювати незалежно від теми, зазвичай підходить окремий плагін або mu-plugin. Якщо логіка безпосередньо стосується оформлення сайту, можна використати дочірню тему. Власні хуки варто розміщувати в місцях, де вони мають чітке призначення та стабільний контракт.
Чи впливають хуки WordPress на продуктивність сайту?
Так, будь-який додатковий код може впливати на продуктивність. Сам факт використання хуків не означає, що сайт працюватиме повільно. Важливі кількість callback, складність їхньої логіки, запити до бази даних, зовнішні HTTP-запити та частота спрацювання хуку.
Найкращий підхід — уникати непотрібних операцій у часто виконуваних callback і вимірювати продуктивність, якщо є підозра на проблему.
Як видалити зареєстрований Action або Filter?
Для видалення callback використовують remove_action() або remove_filter() відповідно. Потрібно передати назву хуку, той самий callback і пріоритет, з якими його було зареєстровано.
Якщо функція зареєстрована з нестандартним пріоритетом, спроба видалити її з пріоритетом за замовчуванням може не спрацювати. Також важливо виконати видалення після реєстрації callback, але до моменту спрацювання самого хуку.
Чи можна зареєструвати декілька callback для одного хуку?
Так. До одного Action або Filter можна під'єднати декілька функцій. Для Action вони виконуватимуть свої операції, а для Filter кожна функція може послідовно змінювати результат попередньої. Порядок визначається пріоритетами та порядком реєстрації.
Висновок
Action і Filter — два базові механізми розширення WordPress, які дозволяють додавати функціональність і змінювати поведінку системи без прямого втручання в її ядро.
Головне правило просте: Action потрібен для виконання операції, Filter — для зміни значення, яке буде використано далі.
Щоб правильно працювати з хуками, потрібно розуміти момент їхнього спрацювання, перевіряти аргументи, враховувати пріоритети та дотримуватися призначення кожного механізму. Якщо ви створюєте власні плагіни, використання добре продуманих хуків також допоможе іншим розробникам розширювати ваш код без його модифікації.
Розуміння WordPress Hooks — важливий крок від простого редагування тем до повноцінної розробки розширень, інтеграцій і підтримуваних WordPress-проєктів.
