Categories: Wordpress - як зробити

Використання запитів WP_Query у WordPress — частина 4 (хуки та фільтри)

Цим уроком ми продовжуємо серію уроків по роботі з запитами до бази даних WP_Query у ВордПрес. Сьогодні ми зосередимось на пов’язаних з запитом фільтрах (filters) та хуках (дії, actions). Це повинно додати вам ще більше впевненості у своїх силах в якості WP-програміста.

Як ви вже знаєте, при роботі з класом WP_Query ми можемо задіювати не лише спеціальні функції, а також додаткові хуки та фільтри. І сьогоднішній практичний урок присвячено саме цьому.

Спеціальні фільтри, що пов’язані з класом `WP_Query`

Давайте детальніше розглянемо фільтри WordPress, що спеціально «налаштовані» під клас WP_Query. В попередньому уроці ми розглянули 10 спеціальних функцій цього класу, а сьогодні продовжимо і розглянемо основні фільтри та хуки WP_Query у WordPress.

Фільтрування кількості знайдених публікацій запиту: `found_posts`

Цей фільтр дозволяє змінювати кількість знайдених елементів, не зважаючи на обмеження, що встановлено аргументом posts_per_page запиту WP_Query.

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

Фільтрування запиту, що слугує для повернення знайдених дописів: `found_posts_query`

Кількість знайдених елементів в результаті запиту обчислюється з допомогою SQL команди SELECT FOUND_ROWS(). А з допомогою цього фільтру ви можете змінити дану команду.

Фільтрування усього SQL запиту: `posts_request`

Якщо ви хочете внести зміни у вже сформований SQL-запит, тоді можете скористатися даним фільтром. Іншими словам, цей фільтр повністю «перероблює» SQL-запит, що був сформований класом WP_Query.

Фільтрування результуючого масиву: `posts_results`

Якщо вам потрібно змінити результуючий PHP масив, що був отриманий в результаті запиту WP_Query (SQL-команди), тоді скористайтеся цим фільтром. Зауважте лише, що даний фільтр працює з необробленим (row) масивом, отриманим SQL запитом.

Фільтрування результуючого (обробленого) масиву: `the_posts`

На відміну від попереднього фільтру posts_results, фільтр the_posts спрацьовує після внутрішньої обробки масиву. Це може бути корисним, наприклад, коли вам потрібна перевірка неопублікованих та закріплених публікацій.

Фільтрування умови `SELECT` в запиті: `posts_fields`

Команда SELECT в SQL запиті визначає, які поля бази даних буде вибрано з результуючих записів, а цей фільтр допоможе «відфільтрувати» її.

Фільтрування умови `LIMIT` в запиті: `post_limits`

Команда LIMIT запиту SQL встановлює обмеження для запиту, і цей фільтр допоможе «відфільтрувати» її.

Фільтрування умови `DISTINCT` запиту: `posts_distinct`

Команда DISTINCT в SQL запиті вказує, що запит має повертати лише унікальні результати, а цей фільтр допоможе «відфільтрувати» її. Початково WP_Query не повертає лише унікальні результати, але коли ви використаєте цей фільтр, запит буде скориговано і буде повернено лише унікальні результати.

Фільтрування умови `WHERE` в запиті: `posts_where`

Команда WHERE в запиті SQL використовується для операторів SELECT, INSERT, UPDATE або DELETE, і з допомогою даного фільтру ви можете «відфільтрувати» її. Хоча в класі WP_Query зроблено всю необхідну роботу для фільтрації результатів, для більшого контролю ви можете використовувати цей фільтр.

ДОДАТКОВО: для фільтрування умови WHERE в запиті після обчислення пейджінгу використовуйте фільтр posts_where_paged. Цей фільтр є ітерацією до фільтра posts_where, який можна використовувати із запитами розбивки на сторінки (пейджінг, paging).

ДОДАТКОВО: для фільтрування умови WHERE у пошуковому запиті використовуйте фільтр posts_search, який можна використовувати для зміни SQL запиту при отриманні результатів пошуку в WordPress.

Фільтрування умови JOIN запиту: `posts_join`

Оператор JOIN SQL-запиту дозволяє працювати з кількома таблицями бази даних, а цей фільтр допоможе «відфільтрувати» його. Але потрібно використовувати його дуже обережно.

ДОДАТКОВО: для фільтрування умови JOIN запиту після обчислення пейджінгу, використовуйте фільтр posts_join_paged, який подібно до posts_where_paged працює із запитами розбивки на сторінки.

Фільтрування речення `ORDER BY` в запиті: `posts_orderby`

Речення (оператор) ORDER BY в SQL запиті використовується для впорядкування запиту (сортування), а цей фільтр допоможе «відфільтрувати» його.

Фільтрування оператору `GROUP BY` в запиті: `posts_groupby`

Оператор (речення) GROUP BY запиту SQL змушує запит повертати «згруповані» результати за стовпцем(цями) бази даних, а цей фільтр допоможе «відфільтрувати» його і вказати, як вам потрібно групувати результати.

Фільтрування всіх складових елементів запиту: `posts_clauses`

Якщо ви хочете мати справу з усіма операторами одночасно, для цього випадку також є відповідний фільтр: posts_clauses. З допомогою цього фільтру у вас буде контроль над елементами запиту SELECT, WHERE, DISTINCT, JOIN, GROUP BY, ORDER BY та LIMIT.

Хуки (дії, екшени, actions), що пов’язані з запитом `WP_Query`

А зараз давайте перейдемо від розгляду фільтрів, що пов’язані з класом WP_Query, до розгляду іншого виду «зачіпок»: хуків.

Якщо потрібно «вклинитися» в запит перед його виконанням: `pre_get_posts`

Перш ніж запит буде проаналізовано, у вас є змога взаємодіяти з ним (наприклад, щоб додати додаткові змінні) з допомогою цього хуку. Нижче наведено практичний приклад можливого застосування (якщо є необхідність виключити певну категорію з основного циклу):

<?php
add_action( 'pre_get_posts', 'sebweo_exclude_some_category' );
function sebweo_exclude_some_category( $wp_query ) {
  //  додайте категорію до масиву категорій для виключення
  $excluded = array( 25 ); // якщо потрібно виключити з циклу категорію під ID 25
  //  $excluded = array( '-1' ); // якщо потрібно виключити найпершу категорію з циклу
  set_query_var( 'category__not_in', $excluded );
  //  $wp_query->set( 'category__not_in', $excluded );  // інший варіант написання попереднього речення
}
?>

Якщо потрібно більше контролю над обробкою запиту: `parse_query`

На відміну від попереднього хуку pre_get_posts, який втручається в запит до встановлення змінних запиту, хук parse_query буде «втручатися» в процес вже після встановлення всіх змінних для запиту. Його можна використовувати, наприклад, якщо вам потрібно перевірити поточні змінні та, при потребі, відкоригувати це.

Якщо вам потрібно змінити об’єкт публікації: `the_post`

Термін the_post може трохи спантеличити, оскільки це може бути назвою хука дії, або пов’язаної з класом WP_Query функції, або ж методом WP_Query класу.

В даному випадку мова піде про дію, яка дозволяє змінювати об’єкт публікації одразу після формування запиту та його встановлення. Тобто, використовуючи цей хук, ви можете безпосередньо змінити результат. Нижче показано простий практичний приклад цього:

<?php
add_action('the_post', 'sebweo_novinky_badge');
function sebweo_novinky_badge($post)
{
  if (is_single() && in_category('novinky')) {
    // якщо це одиночний пост і в категорії з ID (чи слагом) novinky - показати цей бейдж
    echo '<div class="novinky-badge">' . __('НОВИНКИ', 'i18n') . '</div>';
  }
}
?>

Ось і все, тема сьогоднішнього уроку вичерпана. Ви лише поверхово познайомились з хуками та фільтрами, адже це не лише цікава тема, але й дуже комплексна, про яку можна багато говорити та писати. Але це виходить за рамки поточного уроку серії. В подальших уроках дана тема буде детальніше оглянута та розкрита.

В наступній частині уроків ми поговоримо про властивості та методи класу WP_Query, що дозволять вам мати більше контролю над запитом.