Аргументы WP_Query: таксономии

В предыдущих статьях из этой серии мы успели познакомиться со структурой класса WP_Query, а также его параметрами и методами. Теперь пришло время научиться использовать различные аргументы. Сегодня мы познакомим вас с аргументами, необходимыми для запросов к терминам таксономии.

Вспоминаем, как работают аргументы в WP_Query

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

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

На практике это выглядит следующим образом:

<?php

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

// Произвольный запрос
$query = new WP_Query( $args );

// Проверка наличия результатов запроса
if ( $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 может опросить не все указанные вами аргументы, и в итоге на экран ничего не выведется.

Параметры таксономии

Установка параметров для терминов таксономии немного сложнее, так как здесь нужно использовать tax_query. С помощью следующих параметров прописывается вложенный массив аргументов для указания таксономии и термина:

  • taxonomy (string): таксономия;
  • field (string): выбор термина таксономии по (‘term_id (по умолчанию), ‘name‘ или ‘slug‘);
  • terms (int/string/array): Термин(ы) таксономии;
  • include_children (boolean): Включать или нет дочерние элементы из иерархии таксономий. По умолчанию используется значение true;
  • operator (string): Оператор для тестирования. Возможные значения: ‘IN‘ (по умолчанию), ‘NOT IN‘, ‘AND‘.

Благодаря параметру operator, вам не нужно выбирать один из доступных аргументов, чтобы определить включены или исключены термины (как это делается при работе с тегами и рубриками). Вместо этого нужно использовать tax_query для всего, что связано с таксономиями.

Если нужно создать запрос к нескольким таксономиям, можно использовать параметр relation перед всеми вашими массивами (для каждой таксономии), и использовать AND или OR для указания, что вам нужны записи со всеми терминами или с любым из указанных.

Запрос к одному термину таксономии

Это самый простой сценарий, который подразумевает использование лишь одного вложенного массива:

$args = array(
    'tax_query' => array(
        array(
            'taxonomy' => 'my-taxonomy',
            'field' => 'slug',
            'terms' => 'my-term-slug',
        )
    )
);

Этот код запрашивает записи с термином my-term-slug в таксономии my-taxonomy. Вам также нужно будет указать параметр field для определения поля, которое вы используете для идентификации термина (если только вы не используете ID термина, который обычно установлен по умолчанию). Если нужно использовать ID термина, то запрос будет выглядеть следующим образом:

$args = array(
    'tax_query' => array(
        array(
            'taxonomy' => 'my-taxonomy',
            'terms' => '11'
        )
    )
);

Использование ID в будущем может усложнить процесс идентификации того, что именно должен искать ваш запрос, но позволит избежать проблем, если никто из пользователей и редакторов не будет изменять короткие имена терминов.

Делаем запрос к нескольким терминам в одной таксономии

Если нужно определить записи с одним и более термином в одной и той же таксономии, то нужно создать вложенный массив, состоящий из терминов.

Чтобы запросить записи с любым ID из списка терминов таксономии, можно использовать следующий код:

$args = array(
    'tax_query' => array(
        array(
            'taxonomy' => 'my-taxonomy',
            'terms' => array(
                '11',
                '12'
            )
        )
    )
);

Если нужно запросить записи со всеми этими терминами, то можно воспользоваться параметром operator внутри вложенного массива:

$args = array(
    'tax_query' => array(
        array(
            'taxonomy' => 'my-taxonomy',
            'terms' => array(
                '11',
                '12'
            ),
            'operator' => 'AND'
        )
    )
);

Обратите внимание, что в первом примере используется оператор IN для поиска записей с любым из терминов. Но это настройка по умолчанию, поэтому не нужно указывать его в аргументах.

Есть еще один сценарий, когда нужно сделать запрос записей, в которых нет ни одного из указанных в массиве терминов одной таксономии:

$args = array(
    'tax_query' => array(
        array(
            'taxonomy' => 'my-taxonomy',
            'terms' => array(
                '11',
                '12'
            ),
            'operator' => 'NOT IN'
        )
    )
);

Здесь мы заменили оператор AND на NOT IN, а это значит, что WordPress найдет записи, которые не содержат термины, указанные в массиве.

Если вы предпочитаете использовать короткие имена вместо ID терминов, то это допустимо во всех сценариях. Последний пример выглядит следующим образом:

$args = array(
    'tax_query' => array(
        array(
            'taxonomy' => 'my-taxonomy',
            'field' => 'slug',
            'terms' => array(
                'my-slug',
                'your-slug'
            ),
            'operator' => 'NOT IN'
        )
    )
);

Еще один сценарий, когда нужно сделать запрос записей, в которых используется один термин, но при этом не используется какой-то другой. Для этого нам понадобится оператор IN (который не нужно указывать, так как он выставлен по умолчанию), но с использованием знака минуса перед ID тех терминов, которые нужно исключить:

$args = array(
    'tax_query' => array(
        array(
            'taxonomy' => 'my-taxonomy',
            'terms' => array(
                '11',
                '-12'
            )
        )
    )
);

Этот код осуществляет запрос записей с термином 11, но без термина 12.

Запрашиваем термины из нескольких таксономий

Для работы с несколькими таксономиями нужно создать больше массивов. Пример, в котором осуществляется запрос записей с одним термином из taxonomy1 и другим из taxonomy2:

$args = array(
    'tax_query' => array(
        'relation' => 'AND',
        array(
            'taxonomy' => 'taxonomy1',
            'field' => 'slug',
            'terms' => array( 'slug-one' )
        ),
        array(
            'taxonomy' => 'taxonomy2',
            'field' => 'slug',
            'terms' => array( 'slug-two' )
        )
    )
);

В этом коде представлено два вложенных массива: один для каждой таксономии, и в них используются те же аргументы, что мы использовали в примерах с одной таксономией. Ранее я уже рассказывала об аргументе relation. Здесь его также нужно использовать, так как он сообщает WordPress о необходимости искать все или некоторые записи для каждого массива.

Это работает следующим образом:

  • Если вы используете ‘relation’ => ‘AND’, WordPress извлечет записи, указанные в первом и втором массивах. В приведенном выше примере мы получим записи как с коротким именем slug-one из taxonomy1, так и записи slug-two из taxonomy2;
  • Если использовать ‘relation’ => ‘OR’, WordPress извлечет записи с терминами из первого или второго массива. То есть в данном случае мы получим записи либо с slug-one, либо с slug-two (или с обоими slug).

Такой код обычно используется, когда нужно найти записи с любым из двух slug:

$args = array(
    'tax_query' => array(
        'relation' => 'OR',
        array(
            'taxonomy' => 'taxonomy1',
            'field' => 'slug',
            'terms' => array( 'slug-one' )
        ),
        array(
            'taxonomy' => 'taxonomy2',
            'field' => 'slug',
            'terms' => array( 'slug-two' )
        )
    )
);

Вы также можете осуществить поиск записей с более чем одним термином в заданной таксономии, просто добавив их в массив:

$args = array(
    'tax_query' => array(
        'relation' => 'OR',
        array(
            'taxonomy' => 'taxonomy1',
            'field' => 'slug',
            'terms' => array( 'slug-one' )
        ),
        array(
            'taxonomy' => 'taxonomy2',
            'field' => 'slug',
            'terms' => array(
                'slug-two',
                'slug-three'
            )
        )
    )
);

Комбинируя аргумент relation с вложенными запросами при использовании аргумента argument, вы сможете создавать достаточно сложные запросы. В этом примере аргументы будут запрашивать записи с термином из одной таксономии, но с исключением термина из другой таксономии:

$args = array(
    'tax_query' => array(
        'relation' => 'AND',
        array(
            'taxonomy' => 'taxonomy1',
            'field' => 'slug',
            'terms' => array( 'slug-one' ),
            'operator' => 'NOT IN'
        ),
        array(
            'taxonomy' => 'taxonomy2',
            'field' => 'slug',
            'terms' => array( 'slug-two' )
        )
    )
);

Здесь мы использовали ‘relation’ => ‘AND’. Если бы здесь было OR, то запрос был бы направлен к записям с термином slug-two и записям без термина slug-one, вместо того, чтобы обращаться к записям, в которых используется slug-two, но не используется slug-one.

Можно использовать аргумент operator в обоих вложенных запросах или добавить дополнительный вложенный запрос для получения терминов из других таксономий.

Примечание к аргументу tax

Вам, наверное, интересно, почему я не использовала аргумент {tax}, и вместо этого использую код:

$args = array(
    'taxonomy1' => 'slug-one'
);

С аргументом {tax} знакомы лишь немногие, и на данный момент он считается устаревшим, поэтому я не рекомендую его использовать.

В завершение

Создавать запросы для таксономий немного сложнее, чем к рубрикам и тегам из-за использования аргумента tax_query.

Но это достаточно мощный аргумент, который обладает большой гибкостью.

Перевод статьи “WP_Query Arguments: Taxonomies” был подготовлен дружной командой проекта Сайтостроение от А до Я.