Використання запитів WP_Query у WordPress — частина 3 (основні функції класу)

SebWeo

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

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

Спеціальні функції, що пов’язані з класом WP_Query

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

Функція для отримання змінних запиту: `get_query_var()`

Ця функція має описову назву, що промовляє сама за себе: вона бере глобальний об’єкт $wp_query і отримує з нього загальнодоступну змінну запиту. Вона має два параметри: перший — це змінна, що повертає значення, а другий — значення за замовчуванням (якщо змінна не встановлена):

<?php
$page_number = get_query_var( 'paged', 1 );
$category_name = get_query_var( 'category_name' );
$taxonomy_name = get_query_var( 'taxonomy' );
?>

Функція для отримання окремої публікації: `get_post()`

Якщо розглянута раніше функція get_posts() дозволяє виконувати запит та зберігати його у вигляді масиву, то споріднена функція get_post() дозволяє отримати лише одну публікацію. Ця функція має три додаткові параметри:

ідентифікатор публікації (за замовчуванням — ідентифікатор поточної публікації)
визначення типу представлення отриманого результату: це буде об’єкт (object), ARRAY_A (асоціативний масив) або ж ARRAY_N (числовий масив)
чи потрібно фільтрувати результат. За замовчуванням встановлено raw (необроблений, тобто без фільтрації). Інші значення: edit (редагувати), display (відображати), attribute (атрибут) або js.

<?php
$single_post = get_post( 1, ARRAY_A );
$post_title = $single_post['post_title'];
$post_date = $single_post['post_date'];
?>

Тут потрібно дещо уточнити. Якщо ви не знаєте, що саме використовувати для отримання масиву публікацій, WP_Query чи get_posts(), то у Codex’і є наступна рекомендація: якщо вам потрібен комплексний запит (що поверне дані публікації, її метадані, дані автора та пов’язані коментарі), — тоді вам потрібен клас WP_Query, а якщо вам потрібні лише основні дані публікації — тоді використовуйте функцію get_posts(). І, відповідно, при потребі у одній публікації, — тоді вам функція get_post() в допомогу. Раніше ще була функція ~~get_page()~~ для отримання даних однієї сторінки, але вона вже застаріла, і натомість потрібно використовувати саме get_post().

Функція для перевірки, чи містить запит результати: `have_posts()`

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

<?php
if ( have_posts() ) {
  // TRUE
} else {
  // FALSE
}
?>

Функція для роботи з результуючим циклом запиту: `the_post()`

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

встановлює дані глобальної змінної $post
встановлює значення TRUE для параметра in_the_loop
отримує наступний запис із запиту

<?php
if ( have_posts() ) {
  while ( have_posts() ) {
    the_post();
    // ...
  }
}
?>

Функція для налаштування даних глобального `$post`: `setup_postdata()`

Ця функція встановлює глобальні дані публікації, заповнює глобальні змінні $id, $authordata, $currentday, $currentmonth, $page, $pages, $multipage, $more, $numpages:

<?php
global $post;
setup_postdata( $post );
?>

Функція для скидання запиту: `wp_reset_query()`

Використовуйте цю функцію, якщо ви змінювали основний запит (з допомогою функції query_posts() або хуку pre_get_posts). Приклад використання:

<?php
// після того, як основний запит було змінено
wp_reset_query();
?>

Функція для скидання глобальної змінної `$post`: `wp_reset_postdata()`

Дана функція повертає дані глобальної змінної $post до першої публікації в основному запиті. Краще застосовувати її, якщо ви використовуєте подальші після основного запити. Приклад використання:

<?php
// після подальшого(ших) запитів
wp_reset_postdata();
?>

Функція для очищення поточного циклу: `rewind_posts()`

Функціональність цієї функції полягає в тому, що вона просто «перемотує» (rewinds) цикл, щоб ви могли запустити його знову пізніше. Наприклад, так:

<?php
// після циклу
rewind_posts();
?>

Функція перевірки на «главність» поточного запиту: `is_main_query()`

Цей умовний тег повертає TRUE (істина), якщо поточний запит є основним (головним), і FALSE (хиба) в іншому випадку:

<?php
if ( is_main_query() ) {
  // основний запит
} else {
  // другорядний(ні) запити
}
?>

Функція перевірки на «знаходження в циклі»: `in_the_loop()`

Подібним до попереднього тегу є умовний тег in_the_loop(), що повертає TRUE (істина), якщо ваш код виконується всередині циклу, або FALSE (хиба) в іншому випадку:

<?php
if ( in_the_loop() ) {
  // наш код виконується в циклі
} else {
  // наш код виконується поза циклом
}
?>

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