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

Параметры дат

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

Простые аргументы дат

Для осуществления запросов по датам можно использовать следующие параметры:

  • year (int): четырехзначное указание года (например, 2015);
  • monthnum (int): номер месяца (от 1 до 12);
  • w (int): неделя в году (от 0 до 53). Здесь все зависит от значения «start_of_week«, которое настраивается в панели администрирования;
  • day (int): день месяца (от 1 до 31);
  • hour (int): часы (от 0 до 23);
  • minute (int): минуты (от 0 до 60);
  • second (int): секунды (от 0 до 60);
  • m (int): слитное указание года и месяца (например, 201502).

Представьте, что у вас есть сайт, посвященный каким-либо мероприятиям, и здесь для указания даты мероприятия используется дата публикации записи. Чтобы отобразить все прошедшие и запланированные события за 2015 год, нужно будет использовать следующие аргументы:

$args = array(
    'post_type' => 'event',
    'post_status' => array(
        'future',
        'publish'
    ),
    'year' => '2015'
);

В качестве статуса публикаций я использовала future и publish. Это необходимо, чтобы запланированные записи по умолчанию не учитывались в запросе.

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

$current_year = the_date( 'Y' );
 
$args = array(
    'post_type' => 'event',
    'post_status' => array(
        'future',
        'publish'
    ),
    'year' => $current_year
);

Комплексные аргументы дат

Для создания сложных запросов, можно воспользоваться параметром date_query. Он предоставляет доступ к большему числу параметров:

  • year (int): четырехзначное указание года (например, 2015);
  • month (int): номер месяца (от 1 до 12);
  • week (int): неделя в году (от 0 до 53);
  • day (int): день месяца (от 1 до 31);
  • hour (int): часы (от 0 до 23);
  • minute (int): минуты (от 0 до 60);
  • second (int): секунды (от 0 до 60);
  • after (string/array): выводим записи после указанной даты;
  • before (string/array): выводим записи до указанной даты;
  • inclusive (boolean): дополнение для параметров after/before. Обрабатываются, если значение параметра равно true;
  • compare (string): оператор, который можно использовать для сравнения данных БД с вашими аргументами. Допустимы следующие значения: ‘=’, ‘!=’, ‘>’, ‘>=’, ‘
$args = array(
    'date_query' => array(
        array(
            // Здесь указываются аргументы.        
        )
    )
);

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

$args = array(
    'date_query' => array(
        'relation' => 'AND',
        array(
            // Здесь указываются аргументы.
        ),
        array(
            // Здесь указываются аргументы.
        )
    )
);

Приведенный ниже код извлекает записи, которые совпадают с аргументами в одном из массивов (или в обоих):

$args = array(
    'date_query' => array(
        'relation' => 'OR',
        array(
            // Здесь указываются аргументы.
        ),
        array(
            // Здесь указываются аргументы.
        )
    )
);

Давайте рассмотрим все это на примере. Предположим, вы работаете над сайтом колледжа, и хотите вывести записи за текущий учебный год. Учебный год начинается с 1 сентября 2015, и заканчивается 31 августа 2016, и вам нужно найти все записи за этот промежуток времени:

$args = array(
    'date_query' => array(
        'relation' => 'OR',
        array(
            'year' => '2015',
            'month' => ( '9, 10, 11, 12' )
        ),
        array(
            'year' => '2016',
            'month' => ( '1, 2, 3, 4, 5, 6, 7, 8' )
        )
    )
);

Учтите, что параметр month в качестве аргументов принимает строку запроса, а не массив.

Параметры before и after

Можно определить даты, перед или после которых нужно отобразить записи. Делается это при помощи параметров before и after. Они принимают три аргумента:

  • year (string): принимает четыре цифры года. По умолчанию аргумент пуст;
  • month (string): Месяц в году (от 1 до 12). По умолчанию 12;
  • day (string): День в месяце (от 1 до 31). По умолчанию последний день в месяце.

В качестве даты также можно использовать строку запроса в формате PHP strtotime.

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

$args = array(
    'date_query' => array(
        'relation' => 'AND',
        array(
            'after' => array(
                'year' => '2015',
                'month' => '9'
            ),
            'inclusive' => true
        ),
        array(
            'before' => array(
                'year' => '2016',
                'month' => '8'
            ),
            'inclusive' => true
        )
    )
);

Нужно обратить внимание на пару моментов:

  • Я использовала ‘relation’ => ‘AND’, так как мне нужны записи, которые были опубликованы после начальной и до последней даты;
  • Для каждого из вложенных массивов я использовала ‘inclusive’ => true, чтобы удостовериться, что WordPress извлечет записи, опубликованные в период между сентябрем 2015 и августом 2016.

Такой запрос также можно построить с указанием строки запроса вместо дат:

$args = array(
    'date_query' => array(
        array(
            'after' => 'August 31st, 2015',
            'before' => 'September 1st, 2016',
            'inclusive' => false,
        )
    )
);

Из-за специфики работы строк лучше использовать определенные даты. Если вы используете строку даты, она будет сконвертирована в 00:00 этого же дня. Чтобы все заработало, в строке также придется указывать время или день перед нужной датой.

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

$args = array(
    'post_type' => 'event',
    'post_status' => array(
        'future',
        'publish'
    ),
    'date_query' => array(
        array(
            'year' => date( 'Y' ),
            'month' => date( 'M' ),
            'day' => date( 'D' )
        )
    )
);

Функция date() возвращает текущую дату. Я воспользовалась этой функцией трижды, чтобы точно получить нужный день, месяц и год. Я использовала аргумент post_status для вывода мероприятий, которые также запланированы на сегодня, но позже.

В завершение

Иногда требуются запросы лишь к определенным записям. Используя класс WP_Query, вы можете создавать более конкретные запросы для вывода постов по дате, а при помощи аргументов указать определенные условия.

Аргументы date_query комбинируются с другими параметрами. Например, с post_status, о котором мы уже рассказывали в нашей серии более подробно.

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