Посібник: все про хуки в WordPress
Вам коли-небудь казали, що вирішення вашої проблеми полягає в тому, що вам потрібно «підключитися» до чогось, щоб робити свою справу, або використовували, add_filterне розуміючи, чому це псує речі? Хуки складають основу WordPress і надають теми та плагіни для взаємодії чи змінити код. У цій публікації ми розберемо, що таке хуки, як вони працюють і як ми можемо їх використовувати.
Що таке гачки?
Оскільки WordPress проходить через свій код (увесь шлях від початку завантаження класів, завантаження плагінів, завантаження теми, створення запиту для поточного запиту та, нарешті, відтворення HTML), він проходить через купу «контрольних точок»; гачки. Коли буде виявлено хук, WordPress припинить те, що він робить, і перевірить, чи є якісь функції (у темі, плагіні чи самому WordPress), які зареєстровані для запуску на цьому хуку. Якщо вони є, WordPress запустить усі ці функції, а потім продовжить там, де зупинився.
Це дає змогу плагінам, темам і самому WordPress «підключитися» до певних моментів, щоб додати, наприклад, таблиці стилів у <head>тег теми, змінити спосіб запиту WordPress до публікацій або просто змінити вміст публікації, якщо це потрібно.
Є два типи гачків; дії та фільтри. Вони працюють досить схоже один на одного, але за одним винятком, який ми розглянемо докладніше нижче.
Дії та фільтри
Щоб підключитися до дії або фільтру, вам потрібно визначити, який хук (за його назвою) ви бажаєте використовувати, і визначити зворотний виклик – це ім’я функції, яку ви хочете запустити. У більшості випадків хуки надають параметри або змінні, які мають відношення до хука.
Дії — це просто «контрольні точки» у виконанні WordPress, де ви можете виконати завдання або повторити щось. У деяких рідкісних випадках ви можете змінити об’єкт (зазначений у параметрах), щоб усе наступне виконання працювало з цим зміненим об’єктом.
Фільтри призначені для зміни змінної або результату. Усі хуки фільтрів нададуть змінну, яку ви можете змінити як перший параметр, і дозволять вам змінити її або повернути щось інше.
WordPress запускає багато хуків, але ви можете створити свій власний у своєму плагіні чи темі. Це дозволяє розробникам розширювати та змінювати ваш код; наприклад, зміна плагіна через тему або зміна батьківської теми через дочірню тему.
Багато функцій WordPress, які зазвичай використовуються для друку повідомлень, також є фільтрами або діями. Наприклад, функція the_title()друкує заголовок публікації, але вона також є фільтром.
Давайте розглянемо, як ми підключаємося до них на практиці.
Підключення до дій
Щоб підключитися до дії, ви використовуєте метод add_action(). Як мінімум потрібно два параметри; ім’я хука та зворотний виклик; ім’я функції, яку ви бажаєте запустити. Додатково ви можете вказати пріоритет як третій параметр і визначити кількість аргументів, які будуть передані вашій функції зворотного виклику. Пізніше ми розглянемо два необов’язкові параметри, а поки що ось приклад add_action:
add_action('init', 'my_function_name');
function my_function_name() {
// Do your stuff
}Першим параметром add_actionє назва дії; у цьому випадку init, що є досить поширеним підхопленням WordPress, яке відбувається під час ініціалізації. Другим параметром є ваш зворотній виклик, у даному випадку назва функції, яку ми хочемо запустити. Тоді все, що вам потрібно зробити, це визначити функцію з такою назвою та додати в неї свій код.
Ви також можете використовувати анонімні функції, де ви визначаєте функцію всередині add_actionзамість надання назви функції, наприклад;
add_action('init', function() {
// Do your stuff
});Багато розробників віддають перевагу цьому методу, оскільки це запобігає ризику перевизначення функції PHP з таким самим ім’ям.
Якщо вам потрібно запустити функцію, визначену в класі PHP, вам потрібно надати масив як параметр зворотного виклику; де перший елемент — об’єкт класу, а другий — ім’я функції:
class MyClass {
public function __construct() {
add_action('init', [$this, 'myFunctionName']);
}
public function myFunctionName() {
// Do your stuff
}
}Підключення до фільтрів
Щоб підключитися до фільтра, ви використовуєте функцію add_filter(). Подібно до наведених вище дій, перший параметр – це ім’я фільтра, а другий – ваш зворотній виклик. За бажанням ви можете вказати пріоритет як третій параметр і кількість аргументів як четвертий. Ось приклад add_filter:
add_filter('the_title', 'my_function_name');
function my_function_name($title) {
// Do your stuff
return $title;
}У наведеному вище прикладі ми підключаємося до фільтра the_title(який друкує назву публікації) і повідомляємо WordPress запустити нашу функцію. Усі фільтри завжди надаватимуть один аргумент; змінна, яку потрібно змінити. У своїй функції я назвав це $title, оскільки я знаю, що воно містить назву публікації. Усередині функції я можу змінити її або повністю перевизначити змінну. Важливо пам’ятати, що у фільтрах завжди потрібно повертати змінну. Якщо ви не повернете щось у своїй функції зворотного виклику, змінна буде порожньою. Якби я пропустив інструкцію return у наведеному вище прикладі, жодні заголовки публікацій ніколи б ніде не повторювалися.
Змінний аргумент і правило повернення чогось у вашій функції зворотного виклику – це практично єдина відмінність між фільтрами та діями. Все інше працює так само. Ви можете наслідувати приклади для анонімних функцій і класів, показані для дій вище для фільтрів, а також необов’язкові параметри priority і кількість аргументів; які ми розглянемо далі.
Пріоритет
Третій (необов’язковий) параметр add_actionі add_filterє цілим числом, яке визначає пріоритет вашої функції зворотного виклику. Це корисно у випадках, коли є кілька функцій (не обов’язково від вас у вашій темі чи плагіні, пам’ятайте, що сам WordPress використовує власні хуки), і вам потрібно вирішити, яку з них запустити першою.
Якщо пріоритет не надано, за замовчуванням він дорівнює 10. Чим нижчий пріоритет, тим раніше він запускається, а вищий пріоритет – тим пізніше. Ви не можете надати негативний пріоритет.
Уявіть кілька функцій зворотного виклику, зареєстрованих у init. Якщо для кількох зворотних викликів не надано пріоритет, WordPress запустить їх у тому порядку, в якому вони були знайдені (наприклад, у functions.phpкоді вашого плагіна).
add_action('init', 'my_function_name');
add_action('init', 'my_second_function_name');
add_action('init', 'my_third_function_name', 12);
add_action('init', 'my_fourth_function_name', 1);Це буде порядок, у якому WordPress виконуватиме наведені вище зворотні виклики:
my_fourth_function_name(пріоритет 1)my_function_name(пріоритет 10)my_second_function_name(пріоритет 10, але з’являється пізніше в коді)my_third_function_name(пріоритет 12)
Кількість аргументів
Зазвичай хуки надають деякі додаткові дані, які є релевантними та корисними для функцій зворотного виклику. Наприклад, дія save_post(запускається кожного разу, коли публікація оновлюється) надає два можливі аргументи; ідентифікатор публікації та об’єкт публікації. Це корисно для операцій, які зазвичай потрібно виконувати на цьому хуку (наприклад, якщо ви хочете зберегти мета допису, вам потрібен ідентифікатор допису).
Якщо для дії чи фільтра не було надано жодної кількості аргументів, за умовчанням він дорівнює 1. Ось чому вам не потрібно визначати 1 add_filterдля доступу до змінної, до якої підключено фільтр. Однак дії не можуть передавати аргументи, навіть якщо число аргументів встановлено на 1 за замовчуванням.
Давайте розглянемо приклад визначення кількості аргументів і того, як ми отримуємо до них доступ у нашій функції зворотного виклику:
add_action('save_post', 'my_function_name', 10, 2);
function my_function_name($post_id, $post) {
// Do your stuff
}У наведеному вище прикладі ми наказуємо WordPress передати два аргументи нашій функції зворотного виклику. Пам’ятайте, що нам потрібно визначити пріоритет як третій параметр, тому зазвичай ми визначаємо значення за замовчуванням, яке дорівнює 10. Що стосується нашої функції зворотного виклику, тепер ми можемо визначити ту саму кількість аргументів, яку ми запитували, у прикладі вище було 2.
Якби у наведеному вище прикладі ми встановили кількість аргументів на 1, лише перший аргумент у нашій функції зворотного виклику буде заповнений. Другий, $post, буде невизначеним.
Що, якщо нам потрібні дані, які не були передані в хуку?
Визначити, які аргументи можна передати, повністю залежить від розробника, який створив хук. Це означає, що ви не можете просто нав’язати ті аргументи, які ви бажаєте чи потребуєте у своєму add_actionабо add_filter. На щастя, у більшості випадків у нас є альтернативи для отримання необхідних нам змінних. Якщо ви підключаєтеся до дії чи фільтра, де, як вам відомо, мають бути визначені певні глобальні змінні, ви можете отримати доступ до цих глобальних змінних у своїй функції зворотного виклику. Крім того, WordPress має цілий ряд умовних тегів, які можна використовувати у своїх підключених функціях (за винятком дуже ранніх перехоплень, які відбуваються до того, як WordPress визначає ці умовні теги).
Давайте розглянемо приклад доступу до глобальних змінних. Фільтр the_titleнадає ідентифікатор публікації як необов’язковий аргумент, до якого ми можемо отримати доступ, визначивши його як прийнятний аргумент;
add_filter('the_title', 'my_function_name', 10, 2);
function my_function_name($title, $post_id) {
if ($post_id == 1) {
return 'First post ever!';
}
return $title;
}Однак ми можемо досягти такого ж результату:
Якщо ви знаєте, що глобальна змінна визначається точкою запуску хука, ви можете визначити їх як глобальні у своїй функції зворотного виклику та отримати доступ до даних звідти. Наприклад, визначення global $wp_queryу наведеному вище прикладі також надасть вам доступ до повного об’єкта wp_query у зворотному виклику функції.
Умовні теги WordPress надзвичайно корисні. Якщо ви не підключилися до гачка, який виникає на дуже ранній стадії виконання WordPress, вони доступні. Існують умовні теги для перевірки, на якій сторінці (шаблоні) ви перебуваєте, чи перебуваєте ви в меню чи циклі публікацій, і багато іншого. Наприклад, під час модифікації пост-запиту за допомогою хука pre_get_postsдуже корисно переконатися, що ваш код виконується лише в певних випадках. Наприклад;
add_action('pre_get_posts', 'my_function_name');
function my_function_name($query) {
if (!is_admin()) {
// Do your stuff
}
}Оскільки хук pre_get_postsзапускається як в admin, так і в інтерфейсі, ми можемо використовувати умовний тег, щоб переконатися, що наш код впливає лише на запит інтерфейсу.
Створення власних хуків
Ви можете визначити власні дії та фільтри. Якщо ви розробник теми або плагіна, радимо це зробити, щоб дозволити іншим змінювати ваш код без зміни вихідного коду.
Зареєструйте дію за допомогою do_action(), а зареєструйте фільтр за допомогою apply_filters().
Потрібен do_action()мінімум 1 параметр; ім’я гачка. Майте на увазі, що ім’я хука має бути унікальним (не називайте його, наприклад init, оскільки це основний хук WordPress). Розмістіть do_action()туди, де ви хочете, щоб гачок з’явився. Наприклад, ви можете розмістити хук у своїй темі header.phpвідразу після тіла, щоб визначити хук, де розробники можуть виводити сценарії чи інший вміст.
Ви можете додати скільки do_actionзавгодно параметрів після імені хука. Спробуйте пам’ятати, які дані знадобляться розробникам у ваших хуках, які інакше нелегко отримати.
Потрібно apply_filters()мінімум 2 параметри; ім’я гака та змінна, на якій ви реєструєте фільтр. Наприклад, ваша тема може зареєструвати фільтр навколо деяких класів HTML, щоб дозволити розробникам змінювати або додавати до них:
Як і у випадку з діями, ви можете додати скільки apply_filtersзавгодно параметрів після двох обов’язкових параметрів.
Висновок і корисні ресурси
Я сподіваюся, що завдяки цьому ви досягли чіткого розуміння того, як WordPress запускає більшу частину свого коду, як ви можете змінювати код і як ви як розробник можете дозволити іншим розробникам також вносити зміни у ваш код.