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

Сьогодні ми познайомимося з аргументами для довільних полів (custom fields), але спочатку згадаємо, як використовувати аргументи в WP_Query.

Згадуємо, як працюють аргументи в WP_Query

Коли ви використовуєте WP_Query в темах оформлення або плагінах, доводиться включати код чотири основних елемента:

  • Аргументи для запиту, в яких використовуються параметри;
  • Сам запит;
  • Цикл;
  • Завершальний етап: скидання даних запису.

На практиці це виглядає наступним чином:

have_posts() ) {
// початок циклу обробки даних з результатів запиту
while ( $query->have_posts() ) {
$query->the_post();
// вміст опитуваної запису
}
}
// відновлення вихідних даних запису
wp_reset_postdata();
?>

Аргументи повідомляють WordPress, які дані потрібно отримувати з бази даних:

$args = array(
// Аргументи для вашого запиту
);

Як видно, аргументи укладені в масив.

Створюємо код для аргументів

Існує спеціальний спосіб завдання аргументів в масиві:

$args = array(
‘parameter1’ => ‘value’,
‘parameter2’ => ‘value’,
‘parameter3’ => ‘value’
);

Потрібно укладати параметри та їх значення в одинарні лапки, а також використовувати => між ними. Кожен аргумент поділяється коми. Якщо тут щось зробити неправильно, то WordPress може опитати не всі наведені вами аргументи, і на екран нічого не виведеться.

Параметри довільних полів

Довільні поля (також відомі як метадані записів) можуть використовувати окремий клас WP_Meta_Query. Тому для отримання метаданих запису, можна використовувати або WP_Meta_Query, або WP_Query (який все одно звертається до WP_Meta_Query). Але якщо ви хочете зробити запит метаданих та інших елементів (зразок типу запису), то слід використовувати тільки WP_Query.

Основна відмінність у застосуванні цього класу і WP_Query полягає в тому, що WP_Query дозволяє вам створювати прості аргументи без необхідності використовувати вкладені масиви.

Параметри для простого запиту довільного поля

Основні параметри WP_Query для виконання запитів до довільних полів:

  • meta_key (string): ключ довільного поля;
  • meta_value (string): значення довільного поля;
  • meta_value_num (number): значення довільного поля;
  • meta_compare (string): оператор для тестування ‘meta_value‘. Допустимі значення: ‘=’, ‘!=’, ‘>’, ‘>=’, ‘<’, ‘<=’, ‘LIKE’, ‘NOT LIKE’, ‘IN’, ‘NOT IN’, ‘BETWEEN’, ‘NOT BETWEEN’, ‘NOT EXISTS’, ‘REGEXP’, ‘NOT REGEXP’ або ‘RLIKE’. Значення за замовчуванням: ‘=’.

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

$args = array(
‘meta_key’ => ‘key1’
);

Цей аргумент дозволить отримати всі записи з довільним полем з ключем key1, незалежно від значення. Для присвоювання конкретного значення потрібно додати додатковий аргумент:

$args = array(
‘meta_key’ => ‘key1’,
‘meta_value’ => ‘value1’
);

Такий аргумент виведе всі записи з довільним полем, у якого є ключ key1 зі значенням value1.

Можна також вилучити всі записи з довільним полем, значення якого буде value1, незалежно від ключа. Це необхідно, коли використовується кілька ключів довільного поля з повторюваними значеннями:

$args = array(
‘meta_value’ => ‘value1’
);

Як видно, можна направляти запит до довільного поля по ключу або по значенню, і зовсім необов’язково кожен раз вказувати обидва аргументи.

Використовуємо аргумент meta_compare

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

  • =: Одно. Це значення за замовчуванням. Тобто, якщо ви не використовуєте аргумент meta_compare, WP_Query буде використовувати саме його;
  • !+: Не одно;
  • >: Більше ніж;
  • > = — Більше або дорівнює;
  • < : Менше ніж;
  • LIKE: Цей параметр ігнорує регістр, в якому ви вносите значення. Тут навіть можете використовувати спеціальні символи для пошуку значень;
  • NOT LIKE: Працює за тим же принципом, що і LIKE, тільки абсолютно протилежно;
  • IN: Використовуйте цей параметр з масивом в аргументі ‘value’ для пошуку записів з одним чи кількома значеннями, у масиві;
  • BETWEEN: Використовується з масивом з двох числових значень (зазначених в аргументі meta_value) для пошуку записів значенню довільного поля, що знаходиться між цими двома значеннями (але не рівним їм);
  • NOT BETWEEN: Здійснює запит записів значенню довільного поля, які перебувають за межами зазначеного інтервалу з двох цифрових значень у meta_value.

За допомогою аргументу meta_compare ви можете виключити ключі або значення довільного поля. Для того, щоб отримати всі записи, за винятком тих, у значенні ключа яких використовується key1, потрібно використовувати наступний код:

$args = array(
‘meta_key’ => ‘key1’,
‘meta_compare’ => ‘!=’
);

Можна використовувати значення ‘NOT IN’ в аргументі meta_compare, який також може застосовуватися з рядком з декількох значень:

$args = array(
‘meta_key’ => ‘key1, key2’,
‘meta_compare’ => ‘NOT IN’
);

Цей код виконує запит записів, у яких немає довільних полів зі значеннями key1 або key2. Якщо потрібно запитати запису з певним довільним полем, але не з іншим, то можна використовувати вкладений масив, про який я вам розповім пізніше.

У наведених вище прикладах використовуються нецифровые значення. Ви можете використовувати WP_Query з довільними полями, в яких вказані числові значення, не тільки для вилучення записів з цими значеннями, але і для запитів до тих постів, значення довільних полів яких вище або нижче зазначених. Для прикладу, таке може знадобитися в інтернет-магазині, коли потрібно здійснити пошук товарів дешевше або дорожче вказаної вартості.

Щоб знайти записи із значенням довільного поля вище заданого числа, потрібно використовувати наступний код:

$args = array(
‘meta_key’ => ‘numkey’,
‘meta_value’ => ‘100’,
‘meta_compare’ => ‘>’
);

Цей запит дозволить отримати всі записи із значенням довільного поля яких є значення вище 100. Якщо потрібно запитати записи із значеннями від 100 і вище, то можна використати параметр ‘meta_compare’ => ‘>=’.

Також за допомогою аргументу BETWEEN і масиву можна знаходити записи, в довільних полях яких використовуються значення в певному діапазоні:

$args = array(
‘meta_key’ => ‘numkey’,
‘meta_value’ => array (
‘100’,
‘200’
),
‘meta_compare’ => ‘BETWEEN’
);

Такий запит дозволить знайти всі записи із значенням довільних полів між 100 і 200.

Запити для вкладених довільних полів

Якщо потрібно виконати запит по декількох полів довільним або використовувати більше одного оператора, то можна скористатися вкладеним масивом.

Структура запиту буде наступною:

$args = array(
‘meta_query’ => array(
‘relation’ => «, // Опціональний аргумент.
array(
// тут будуть аргументи `meta_query`.
)
)
);

Структура аргументу ‘meta_query’ у класі WP_Query буде такою ж, як і при використанні класу WP_Meta_Query, про який ми детально поговоримо в наступних статтях.

Після виходу WordPress версії 4.1 стало можна використовувати кілька рівнів вкладених масивів для створення ще більш складних і точних запитів. Структура таких запитів виглядає приблизно так:

$args = array(
‘meta_query’ => array(
‘relation’ => «, // Опціональний аргумент.
array(
‘relation’ => «,
array (
// Перший набір аргументів `meta_query`.
),
array (
// Другий набір аргументів `meta_query`.
)
)
)
);

Такий підхід дозволяє використовувати різні взаємозв’язку на різних рівнях в запиті. Наприклад, можна створити запит записів з одним значенням в одному довільному полі, і обома значеннями в іншому довільному полі.

На завершення

Застосування класу WP_Query для створення запитів метаданих записів (або довільних полів) надає гнучкість при роботі з безліччю різних аргументів у поєднанні з операторами.

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

Переклад статті «WP_Query Arguments: Custom Fields» був підготовлений дружною командою проекту Сайтостроение від А до Я.