query_posts() WP 1.5.0

Используется самим WordPress при получении записей для текущей страницы (архив авторов, отдельная запись, рубрика, метка). Определяет какие посты будут показаны в базовом Цикле WordPress. Создает базовый Цикл WordPress. Возвращает список записей (постов).

Важно: использовать query_posts() может быть опасно

query_posts() предназначена для самого WordPress и должна использоваться для изменения основного Цикла WordPress, если нужно создать еще одни цикл, то используйте get_posts() или WP_Query. С версии 3.0 эти функции могут принимать все те же параметры что и query_posts().

Пример использования get_posts() вместо query_posts():

$args = array( 'posts_per_page' => 3 );
$lastposts = get_posts( $args );
foreach( $lastposts as $post ){ setup_postdata($post);
	?>
	<h2><a href="<?php the_permalink(); ?>"><?php the_title(); ?></a></h2>
	<?php 
	the_content(); 
}
wp_reset_postdata();

Пример использования WP_Query вместо query_posts():

$args = array( 'posts_per_page' => 3 );
$query = new WP_Query( $args );
while ( $query->have_posts() ) {
	$query->the_post();

	the_title(); // выведем заголовок поста
}
wp_reset_postdata();

Почему query_posts() нужно использовать очень аккуратно?

Основной запрос WordPress — это запрос, который выполняется до вывода какого-либо текста на страницу (на раннем этапе). Параметры такого запроса собирает сам WP опираясь на: запрошенный URL; настройки ЧПУ (постоянных ссылок) и др. Так WordPress определяет сколько записей показать на странице, записи из какой рубрики показывать и т.д.

А вторичный запрос это тот, который создается пользователем (темой, плагином) и выполняется дополнительно к основному. Например: Вывод в сайдбаре списка популярных записей; Вывод комментируемых записей.

Так вот, если использовать query_posts() для создания вторичных запросов (циклов), то могут появится ошибки из-за которых будет рушится структура и тип страниц, так как повторный вызов query_posts() переписывает базовый запрос WP, на основе которого определяется тип текущей страницы (запись, рубрика), определяется сколько записей показывать на странице (пагинация) и многое другое.

Разница между query_posts() и WP_Query в том, что query_posts() создает новый WP_Query объект и связывает его с глобальной переменной $wp_query, тогда как get_posts() или WP_Query() создает новый WP_Query объект, без изменения каких-либо глобальных данных.

Давайте рассмотрим на примере:

// Пример 1: Дополнительный запрос с помощью query_posts
query_posts( $args );
while ( have_posts() ) {
	the_post();

	the_title(); // вывести название
}

// Пример 2: Дополнительный запрос с помощью WP_Query
$second_query = new WP_Query( $args );
while ( $second_query->have_posts() ) { $second_query->the_post();

	the_title();
}

Тут, первый пример переписывает глобальные переменные $wp_query, $post, $posts, а второй работает автономно и ничего глобального не трогает.

Чтобы более детально понять разницу прочитайте мою короткую статью: 3 способа построения циклов в WordPress.

Если вы по каким-то причинам вынуждены использовать query_posts(), то после цикла обязательно используйте wp_reset_query() - сбрасывает глобальные переменные запроса на начальные.

Если не сбросить цикл с помощью wp_reset_query(), то, например, может поломаться пагинация (это самый яркий пример из жизни) — это когда первая страница работает, а остальные показывают 404 страницу.

О query_posts()

Функция может принимать массу различных параметров, которые можно указывать как в виде массива, так и в виде строки (cat=4&posts_per_page=5).

Благодаря этой функции можно изменить стандартный вывод постов в WordPress. Вывод формируется на основе того, какая страница показывается (главная, архив по дате, категория, архив автора и т.п.). Например, можно изменить цикл так:

• Показывать только один пост на главной странице блога;
• Показывать последние посты только на главной странице блога;
• Изменить порядок сортировки постов;
• Показывать или не показывать посты из определенной категории.

Хуков нет.

Возвращает

Объект. Глобальный объект wp_query, предварительно устанавливает его.

Использование

<?php
// Запрос. $args - параметры запроса
query_posts( $args );

// Цикл WordPress
if( have_posts() ){ 
	  while( have_posts() ){ 
		   the_post();
		   // здесь оформляем данные для каждого поста в цикле
	  }
	  wp_reset_query();
} else {
   // текст/код, если постов нет
}
?>

Например, давайте изменим порядок сортировки постов, при этом не затрагивая остальные параметры запроса, для этого нужно написать такой код перед Циклом WordPress:

global $query_string;
query_posts($query_string . "&order=ASC");

В этом примере "порция" добавочных аргументов должна претворятся знаком амперсанд (&)

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

global $query_string;
// добавляем базовые параметры в массив $args
parse_str($query_string, $args);
// добавляем/заменяем параметр post_type в массиве
$args['post_type'] = array('post','video');
query_posts( $args );

На заметку

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

• posts_distinct - Изменяет SQL 'DISTINCTROW';
• posts_groupby - Изменяет SQL 'GROUP BY';
• posts_join - Изменяет SQL 'JOIN';
• post_limits - Изменяет SQL 'LIMIT';
• posts_orderby - Изменяет SQL 'ORDER BY';
• posts_where - Изменяет SQL 'WHERE';
• posts_join_paged - Изменяет SQL 'JOIN' во время пагинации;
• posts_where_paged - Изменяет SQL 'WHERE' во время пагинации;
• posts_clauses (с версии 3.1) - Изменяет весь SQL запрос в одной строке.

Параметры

Ниже представлены все параметры, которые может принимать функция query_posts(), по разделам:

Параметры Категорий (рубрик)

Получает посты относящиеся к определенным категориям.

cat(число)

ID категории.

category_name(строка)

Имя категории. Используйте слаг (альтернативное имя), а не само название категории.

category__and(массив)

Получить посты, которые входят одновременно в несколько категорий.

category__in(массив)

Получить посты, которые входят в одну из указанных категорий.

category__not_in(массив)

Получить посты, которые не входят в указанную категорию.

Посты из одной категории

Вывод постов из одной категории (записи из дочерних категорий так же будут выбраны):

query_posts('cat=4');

вывод постов из одной категории по слагу (альтернативному названию категории):

query_posts('category_name=staff');

Выведем посты только из категории 4 (дочерние категории не затрагиваются):

query_posts( 'category__in=4' );

Посты из нескольких категорий

Вывод постов из категорий по ID категорий:

query_posts('cat=2,6,17,38');

Выведем посты из категорий по слагу категорий:

query_posts( 'category_name=staff,news' );

Исключим посты принадлежащие категориям

Выведем все посты, кроме постов из категорий 12,34,56:

query_posts( 'cat=-12,-34,-56' );

Показать все посты, кроме тех, что принадлежать категории 3:

query_posts('cat=-3');

Нескольких категорий одновременно

Показать посты, которые находятся сразу в двух категориях:

query_posts( array( 'category__and' => array(2,6) ) );

Показать посты которые находятся хотя бы в одной из категорий (дочерние категории не будут учитываться):

query_posts(array('category__in' => array(2,6)));

Можно исключить несколько категорий, таким образом:

query_posts( array('category__not_in' => array(2,6)) );

Параметры Меток

Получает посты относящиеся к определенным меткам.

tag(строка)

slug метки.

tag_id(число)

ID категорий.

tag__and(массив)

Посты одновременно из нескольких меток. Нужно указывать ID.

tag__in(массив)

Посты из хотя бы одной указанной метки. Нужно указывать ID.

tag__not_in(массив)

Посты не относящиеся к указанным меткам. Нужно указывать ID.

tag_slug__and(массив)

Тоже что и tag__and, только указываются альт. названия (slug) меток.

tag_slug__in(массив)

тоже что и tag__in, только указываются альт. названия меток.

Посты с одной меткой

Получить посты с меткой:

query_posts('tag=cooking');

Указывать нужно альтернативное название метки.

Получить посты, имеющие хотя бы одну указанную метку:

query_posts('tag=bread,baking');

Посты с несколькими метками

Получить посты имеющие любую из меток:

query_posts( 'tag=bread,baking' );

Получить посты, имеющие сразу все указанные метки:

query_posts('tag=bread+baking+recipe');

Получить посты, имеющие сразу две метки (37 и 47):

query_posts( array('tag__and' => array(37,47)) );

Этот вариант более предпочтителен вышеприведенному из-за быстродействия.

Получить посты, имеющие хотя бы одно метку 37 или 47:

query_posts( array('tag__in' => array(37,47)) );

Этот вариант предпочтительнее т.к. указываются сразу ID.

Получить посты, НЕ связанные с метками 37 или 47:

query_posts(array('tag__not_in' => array(37,47)));

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

Выводит посты связанные с определенной таксономией.

{tax}(строка)

Использовался в версиях ниже 3.1 для которого нужно было указывать "название термина" ( array('taxonomy_name'=>'categoriya') ). Запрещен с версии 3.1.

tax_query(массив)

С версий 3.1 и выше используется аргумент tax_query, который имеет ряд вложенных аргументов, это:

• relation (строка)
  Как выбирать записи из указанных таксономий. Указывается в первом массиве, а термины во вложенных. Может быть:
  AND - записи которые одновременно входят в указанные таксономии;
  OR - записи принадлежащие любой из указанных таксономий.

  • taxonomy (строка) - Название таксономии

  • field (строка)
    Поле которое будет указывать в параметре terms. Может быть: id, term_id, name или slug.
    id/term_id - значит в terms указываем id терминов.
    slug - значит в terms указываем альтернативное название терминов.
    name - значит в terms указываем заголовок термина.
    По умолчанию: 'term_id'

  • terms (число/строка/массив)
    Термины таксономии, из которых нужно вывести записи.

  • operator (строка)
    Оператор, указывающий как сравнивать указанные термины в параметре terms. Может быть:
    IN - записи из указанных терминов (по умолчанию);
    NOT IN - записи из всех терминов, кроме указанных;
    AND - записи одновременно принадлежащие всем указанным терминам;
    EXISTS - (с версии 4.1) существует;
    NOT EXISTS - (с версии 4.1) не существует.
    По умолчанию: 'IN'

  • include_children (логический)
    Включать или нет посты из дочерних терминов (для древовидных таксономий). true -включить.
    По умолчанию: true

Вывод из одной таксономии

Выведем записи из раздела (термина) bob, который является элементом таксономии people:

query_posts( array( 'people' => 'bob' ) );

Выведем посты прикрепленные к термину bob из таксономии people:

$args = array(
	'post_type' => 'post',
	'people' => 'bob'
);
query_posts( $args );

Сделаем тоже самое что и в примере выше, только с использованием аргумента tax_query:

$args = array(
	'tax_query' => array(
		array(
			'taxonomy' => 'people',
			'field' => 'slug',
			'terms' => 'bob'
		)
	)
);
query_posts( $args );

Вывод из нескольких таксономии

Выведем посты из нескольких произвольных таксономий:

$args = array(
	'post_type' => 'post',
	'people' => 'bob',
	'language' => 'english'
);
query_posts( $args );

Аналог примера выше. Выведем записи, который одновременно относятся к нескольким произвольным таксономиям через tax_query:

$args = array(
	'tax_query' => array(
		'relation' => 'AND',
		array(
			'taxonomy' => 'movie_janner',
			'field' => 'slug',
			'terms' => array( 'action', 'commedy' ),
		),
		array(
			'taxonomy' => 'actor',
			'field' => 'id',
			'terms' => array( 103, 115, 206 ),
			'operator' => 'NOT IN',
		)
	)
)
query_posts( $args );

Выведем посты которые находятся в рубрике quotes или которые имеют формат quote (форматы введены в версии 3.1). Для этого используем аргумент relation:

$args = array(
	'post_type' => 'post',
	'tax_query' => array(
		'relation' => 'OR',
		array(
			'taxonomy' => 'category',
			'field' => 'slug',
			'terms' => array( 'quotes' )
		),
		array(
			'taxonomy' => 'post_format',
			'field' => 'slug',
			'terms' => array( 'post-format-quote' )
		)
	)
);
query_posts( $args );

Использование get_posts()

# 5. Выведем заголовки всех типов записей countries из всех подрубрик термина 62, который относится к таксономии country:

$args = array(
	'tax_query' => array(
		array(
			'taxonomy' => 'country',
			'field' => 'id',
			'terms' => array( 62 )
		)
	),
	'post_type' => 'countries',
	'posts_per_page' => -1
);
$posts = get_posts( $args );

foreach( $posts as $pst ){
	echo $pst->post_title .'<br>';
}

#6. Выведем все записи произвольного типа (article) не относящиеся к указанным терминам ('term-slug', 'term-slug-two', 'term-slug-three') таксономии (artictag):

## получим все посты не относящиеся к указанным терминам
$post_type = 'article';
$tax = 'artictag';
$terms = array('term-slug', 'term-slug-two', 'term-slug-three');
$psts = get_posts( array(
	'posts_per_page' => -1,
	'post_type' => $post_type,
	'tax_query' => array(
			'relation' => 'AND',
			array(
				'taxonomy' => $tax,
				'terms' => $terms,
				'field' => 'slug',
				'operator' => 'NOT IN',
			)
		),
	'' => '',
) );

$i = 0;
foreach( $psts as $pst ){
	echo ++$i . ' <a href="'. get_permalink( $pst->ID ) .'">'. $pst->post_title .'</a><br>';
}

Параметры Авторов

Получает посты принадлежащие определенным авторам.

author(число)

ID автора.

author_name(число)

Ник автора. Нужно указывать значение поля user_nicename.

#1 Выведем посты для одного автора

Посты по ID автора:

query_posts( 'author=123' );

Посты по нику автора:

query_posts( 'author_name=rami' );

#2 Выведем посты нескольких авторов сразу

Посты четырех авторов по ID:

query_posts( 'author=2,6,17,38' );

#3 Исключим посты автора

Исключим посты автора 12 и покажем все посты, кроме его:

query_posts( 'author=-12' );

#4 Еще пример

Показать все страницы автора 1 (author=1), отсортировать по заголовку (orderby=title) в алфавитном порядке (order=ASC) и не показывать прикрепленные посты вверху.

query_posts('caller_get_posts=1&author=1&post_type=page&post_status=publish&orderby=title&order=ASC');

Параметры Постов и Страниц

Получает отдельные страницы или посты.

p(число)

ID поста который нужно получить (p=27).

name(строка)

Альт. название поста (name=o-saite).

page_id(число)

ID постоянной страницы, которую нужно получить (page_id=27)

pagename(строка)

Альт. название постоянной страницы (pagename=o-saite)

post_parent(число)

Вернет только дочерние страницы.

post_parent__in(массив)

Выберет посты родители которых указанны в массиве.

post_parent__not_in(массив)

Выберет посты родители которых не указанны в массиве.

post__in(массив)

Укажите через запятую ID постов, которые нужно получить (post__in=5,12,2,14,7).

Внимание: если вы использует прилепленные посты, они будут включены, хотите вы того или нет. Чтобы это исправить, используйте параметр ignore_sticky_posts

post__not_in(массив)

Выведет все посты кроме указанных.

Посты/страницы по ID

Выведем пост по ID:

query_posts('p=7');

Выведем страницу по ID:

query_posts( 'page_id=7' );

Посты/страницы по Слагу

Выведем пост по Слагу:

query_posts( 'name=about-my-life' );

Выведем страницу по Слагу:

query_posts( 'pagename=contact' );

Дочерние посты/страницы

Выведем дочернюю страницу, используя слаг родительской и дочерней страницы разделенные слэшом: parent_slug/child_slug

query_posts( 'pagename=contact_us/canada' );

Выведем дочерние страницы, используя ID родительской:

query_posts( 'post_parent=93' );

Выведем страницы верхнего уровня, исключим все дочерние:

query_posts( 'post_parent=0' );

Выведем посты родители которых указаны в массиве:

query_posts( array( 'post_parent__in' => array( 2, 5, 12, 14, 20 ) ) );

Множественные выводы постов/страниц

Выведем только указанные посты:

query_posts( 
	array( 'post_type' => 'page', 'post__in' => array( 2, 5, 12, 14, 20 ) ) 
);

Выведем все посты, кроме указанных:

query_posts( array(
	'post_type' => 'post',
	'post__not_in' => array( 2, 5, 12, 14, 20 )
) );

Заметка: вы не можете объединять post__in и post__not_in в одном запросе.

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

// не правильно
$exclude_ids = '1,2,3';
query_posts( array( 'post__not_in' => array( $exclude_ids ) ) );

// Правильно
$exclude_ids = array( 1, 2, 3 );
query_posts( array( 'post__not_in' => $exclude_ids ) );

Параметры Произвольных полей (postmeta)

Основным параметром для работы с мета-данными в WP_Query является meta_query, который получает записи (посты) по существующим у них произвольным полям и их значениям. По принципу использования, meta_query похож на tax_query - массив, где каждый элемент в свою очередь является массивом с параметрами запроса, т.е. meta_query - это массив массивов:

$args = array(
	'meta_query' => array(
		'relation' => 'OR',
		array(
			'key' => 'color',
			'value' => 'blue'
		),
		array(
			'key' => 'price',
			'value' => 20
		)
	)
);

Такая конструкция позволяет использовать множественные запросы. Первый параметр relation во "внешнем" массиве описывает логическую связь между запросами. Он может принимать значения AND (используется по умолчанию. Совпадение со всеми запросами) или OR (совпадение с любым из запросов).

Старые переменные запроса мета-данных: meta_key, meta_value, meta_value_num, meta_compare по прежнему поддерживаются и могут быть использованы для простых запросов связанных с произвольными полями.

Список всех параметров связанных с мета-данными:

meta_key(строка)

Ключ(название) произвольного поля.

meta_value(строка)

Значение произвольного поля.

meta_value_num(число)

Значение произвольного поля, число.

meta_compare(строка)

Оператор для проверки значения произвольного поля. Может быть: =, !=, >, >=, <, <=, LIKE, NOT LIKE, IN, NOT IN, BETWEEN, NOT BETWEEN, EXISTS (с версии 3.5), NOT EXISTS (3.5), REGEXP (3.7), NOT REGEXP (3.7) и RLIKE (3.7);
По умолчанию '='

meta_query(массив)

Массив параметров мета-данных определяющих вывод (этот параметр включает в себя meta_key, meta_value и meta_compare и заменяет их). С версии 3.1.
В массиве можно указать следующие параметры:

• relation (строка)
  Этот параметр указывается как строка в главном массиве meta_query и указывает как сравнивать между собой несколько массивов с параметрами запроса, указанных в этом главном массиве.
  Параметр может принимать два значение:
  OR - выбрать мета-поля подходящие хоты бы под один массив с параметрами запроса;
  AND (по умолчанию) - выбрать мета поля подходящие для всех массивов с параметрами запроса.

  • key (строка)
    Ключ поля.

  • value (строка/массив)
    Значение поля. Указывать не нужно, если при сравнении используется: 'EXISTS' или 'NOT EXISTS' (с версии 3.9).

  • compare (строка)
    Cравнение. может быть: =, !=, >, >=, <, <=, LIKE, NOT LIKE, IN, NOT IN, BETWEEN, NOT BETWEEN, EXISTS (с версии 3.5), NOT EXISTS (3.5), REGEXP (3.7), NOT REGEXP (3.7) и RLIKE (3.7);
    По умолчанию '='

  • type (строка)
    тип произвольного поля (если, например в поле указываются только числа то нужно использовать NUMERIC, чтобы числа не сравнивались как строки). Может быть: NUMERIC, BINARY, CHAR, DATE, DATETIME, DECIMAL, SIGNED, TIME, UNSIGNED. По умолчанию: CHAR.

  Тип DATE работает при сравнении BETWEEN только если дата указывается в формате YYYYMMDD и сравнивается с аналогичным форматом.

Сортировка по произвольному полю

Для сортировки по полю, нужно указать ключ данных поля, и затем в параметре 'orderby' указать название этого ключа, например:

'meta_query' => array(
	'book_color' => array(
		'key'     => 'color',
		'value'   => 'blue',
		'compare' => 'NOT LIKE',
	),
),
'orderby' => 'book_color',
'order'   => 'DESC',

Если произвольное поле указывается через параметр meta_key и meta_value, то для сортировки по этому полю в параметре orderby укажите значения: meta_value или meta_value_num (для чисел). См. ниже описание параметра orderby.

'meta_key=color&meta_value=blue&orderby=meta_value&order=ASC'

Базовые примеры (без meta_query)

#1 Посты с ключом произвольного поля color, не обращая внимание на значение этого поля.

query_posts( 'meta_key=color' );

#2 Посты со значением произвольно поля blue, не обращая внимание на название ключа.

query_posts( 'meta_value=blue' );

#3 Посты с ключом поля color и значением этого поля blue:

query_posts( array( 'meta_key' => 'color', 'meta_value' => 'blue' ) );

#4 Посты у которых ключ равен color и значение поля не равно blue:

query_posts( 
	 array( 'meta_key' => 'color', 'meta_value' => 'blue', 'meta_compare' => '!=' ) 
);

#5 Продукты с ключом price и значение произвольно поля меньше или равно 22.

При использовании параметра "meta_value" значение 99 будет больше 100, так как эти значения распознаются как строки, а не числа. Для того чтобы числа понимались как числа нужно использовать параметр "meta_value_num":

query_posts( 
	 array( 'meta_key' => 'price', 'meta_value_num' => '22', 'meta_compare' => '<=', 'post_type' => 'product' ) 
);

#6 Посты со значением произвольного поля равным 0, не важно какой ключ.

query_posts( array ( 'meta_value' => '_wp_zero_value' ) );

Примеры с использованием meta_query

#1 Записи с одним произвольным полем

Выведем продукты (product) у которых ключ равен color и значение поля не равно blue:

$args = array(
	'post_type'  => 'product',
	'meta_query' => array(
		array(
			'key'     => 'color',
			'value'   => 'blue',
			'compare' => 'NOT LIKE'
		)
	)
);
query_posts( $args );

#2 Записи имеющие одновременно два произвольных поля

Пример вывода постов с несколькими произвольными полями и указанием различных условий для значений этих произвольных полей:

$args = array(
	'post_type'  => 'product',
	'meta_query' => array(
		array(
			'key'     => 'color',
			'value'   => 'blue',
			'compare' => 'NOT LIKE'
		),
		array(
			'key'     => 'price',
			'value'   => array( 20, 100 ),
			'type'    => 'numeric',
			'compare' => 'BETWEEN'
		)
	)
 );
query_posts( $args );

#3 Записи имеющие хотя бы одно поле

Выведем посты с ключом color и значением не (NOT LIKE) blue или (OR) посты с ключом price со значениями поля от 20 до 100:

$args = array(
	'post_type'    => 'product',
	'meta_query'   => array(
		'relation' => 'OR',
		array(
			'key'     => 'color',
			'value'   => 'blue',
			'compare' => 'NOT LIKE'
		),
		array(
			'key'     => 'price',
			'value'   => array( 20, 100 ),
			'type'    => 'numeric',
			'compare' => 'BETWEEN'
		)
	)
);
query_posts( $args );

#4 Записи с двумя полями отсортированные по третьему полю

Предположим у нас есть тип записей toys - игрушки, а в произвольных полях мы указываем материал: твердая мягкая и вес игрушки в граммах: 100 300 500.

Получим мягкие игрушки вес которых от 200 до 500 грамм и отсортируем их по цене по убыванию:

$args = array(
	'post_type'  => 'toys',
	'meta_query' => array(
		array(
			'key'   => 'type',
			'value' => 'soft',
		),
		array(
			'key'     => 'weight',
			'value'   => array( 200, 500 ),
			'compare' => 'BETWEEN',
			'type'    => 'NUMERIC',
		),
	),
	'meta_key' => 'price',
	'orderby'  => 'meta_value_num',
	'order'    => 'DESC'
);
query_posts( $args );

#5 Получим записи у которые есть произвольное поле

Этот пример показывает, как получить записи для которых установлены миниатюры (у которых есть произвольное поле _thumbnail_id):

$args = array(
	'posts_per_page' => 3,
	'post_type'  => 'post',
	'meta_query' => array(
		array(
			'key' => '_thumbnail_id',
			'compare' => 'EXISTS'
		)
	)
);
query_posts( $args );

#6 Вложенные сложные запросы

С версии 4.1 можно создавать вложенные запросы. Например, выполним такое условие: нужно показать продукты оранжевого цвета (color=orange) ИЛИ маленькие (size=small) продукты красного цвета (color=red):

$args = array(
	'post_type'  => 'product',
	'meta_query' => array(
		'relation' => 'OR',
		array(
			'key'     => 'color',
			'value'   => 'orange',
			'compare' => '=',
		),
			array(
					'relation' => 'AND',
					array(
							'key'     => 'color',
							'value'   => 'red',
							'compare' => '=',
					),
					array(
							'key'     => 'size',
							'value'   => 'small',
							'compare' => '=',
					),
		),
	),
);
query_posts( $args );

#7 Сортировка по произвольному полю

С версии 4.2 массивам в meta_query можно указывать ключи, чтобы затем сортировать по этому ключу:

$args = array(
	'post_type'  => 'book',
	'meta_query' => array(
		'book_color' => array(
			'key'     => 'color',
			'value'   => 'blue',
			'compare' => 'NOT LIKE',
		),
	),
	'orderby' => 'book_color',
);
query_posts( $args );

Параметры Типов постов

Показывает посты указанного типа.

post_type(строка/массив)

Записи какого типа нужно показывать. Может быть:

• any - включает все типы, кроме revision и типов у которых указан параметр exclude_from_search=true.
• attachment - по умолчанию WP_Query ставит статус 'post_status'=>'publish', а вложения имеют статус 'post_status'=>'inherit', поэтому чтобы вывести вложения нужно еще изменить параметр post_status на 'inherit' или 'any'.
• page - страница.
• post - пост.
• revision - ревизия.
• Так же можно указывать произвольные типы постов, если таковые имеются.

По умолчанию показываются записи типа post

Посты по типу

Выведем только страницы:

query_posts( 'post_type=page' );

Выведем все посты, кроме ревизий и типов постов у которых при регистрации параметр exclude_from_search выставлен в true:

query_posts( 'post_type=any' );

Выведем 4 типа постов одновременно:

query_posts( array(
	'post_type' => array( 'post', 'page', 'movie', 'book' )
) );

Параметры Статусов

Получает посты с указанным статусом.

post_status(строка/массив)

Статус поста. По умолчанию "publish", а если пользователь авторизован добавляется еще и private. Если запрос запущен из админ части, добавляются еще и защищенные типы статусов, это: 'future', 'draft' и 'pending'. Все типы статусов:

• publish - опубликованный пост;
• pending - пост на модерации;
• draft - черновик;
• auto-draft - черновик, сохраненный самим WordPress (авто-сохранение);
• future - запланированный пост;
• private - личный пост;
• inherit - ревизия;
• trash - удаленный пост (в корзине). С версии 2.9;
• any - все статусы, кроме типов постов с "exclude_from_search=true".

По умолчанию: 'publish'

Посты по статусам

Получим только черновики:

query_posts( 'post_status=draft' );

Получим посты с разными статусами:

query_posts( 
	 array( 'post_status' => array( 'pending', 'draft', 'future' ) ) 
);

Получим все виды вложений:

query_posts( 
	  array( 'post_status' => 'any', 'post_type' => 'attachment' ) 
);

Параметры Даты (времени)

Выводит посты принадлежащие определенному периоду времени.

year(число)

4 цифры года (2013)

monthnum(число)

Номер месяцы (1 - 12)

w(число)

Неделя в году (с 0 до 53)

day(число)

День месяца (1 - 31)

hour(число)

Час (0 - 23)

minute(число)

Минута (0 - 60)

second(число)

Секунда (0 - 60)

m(число)

ГодМесяц (201306)

date_query(массив)

Работает на основе отдельного класса: WP_Date_Query.

• column — поле в базе данных для запроса. По умолчанию post_date. Может быть: 'post_date', 'post_date_gmt', 'post_modified', 'post_modified_gmt', 'comment_date', 'comment_date_gmt'.

• compare — каким оператором производить сравнение. Может быть: =, !=, >, >=, <, <=, IN, NOT IN, BETWEEN, NOT BETWEEN.

• relation — оператор, если указаны несколько массивов с датами: AND (учитывать одновременно все указанные массивы) или OR (если есть совпадения хотя бы с одним указанным массивом). По умолчанию - OR

  • Эти параметры, которые должны использоваться во вложенном массиве. Они определяют сам запрос. Список параметров:
  • before (строка/массив) — строка или массив с датой "до"
  • after (строка/массив) — строка или массив с датой "после"
  • column (строка) — см. выше, только для конкретной даты. По умолчанию значение верхнего массива
  • compare (строка) — см. выше, только для конкретной даты. По умолчанию '='
  • inclusive (логический) — аргументы before и after обрабатываются включительно, если true
  • year (число/массив) — год, например 2013
  • month (число/массив) — месяц, 1-12
  • week (число/массив) — неделя, 0-53
  • day (число/массив) — день, 1-31
  • dayofweek (число/массив) — день недели, 1-7
  • hour (число/массив) — час, 0-23
  • minute (число/массив) — минута, 0-60
  • second (число/массив) — секунда, 0-60

Общие примеры

#1. Получим посты за сегодня:

$today = getdate();
query_posts( 'year=' . $today["year"] . '&monthnum=' . $today["mon"] . '&day=' . $today["mday"] );

#2. Получим посты за последнюю неделю:

$week = date('W');
$year = date('Y');
query_posts( 'year=' . $year . '&w=' . $week );

#3. Получим посты за 20 Декабря:

query_posts( 'monthnum=12&day=20' );

#4. Получим посты за промежуток времени с 1 марта по 15 марта 2010 года:

// Создадим новую функцию которая добавит условие where в запрос
function filter_where( $where = '' ) {
	// с 1 марта по 15 марта 2010 года
	$where .= " AND post_date >= '2010-03-01' AND post_date < '2010-03-16'";
	return $where;
}

add_filter( 'posts_where', 'filter_where' );
query_posts( $query_string );
remove_filter( 'posts_where', 'filter_where' );

#5. Получим посты за последние 30 дней:

// Создадим новую функцию которая добавит условие where в запрос
function filter_where( $where = '' ) {
	// за последние 30 дней
	$where .= " AND post_date > '" . date('Y-m-d', strtotime('-30 days')) . "'";
	return $where;
}

add_filter( 'posts_where', 'filter_where' );
query_posts( $query_string );
remove_filter( 'posts_where', 'filter_where' );

#6. Получим посты за промежуток от 30 до 60 дней, до настоящего:

// Создадим новую функцию которая добавит условие where в запрос
function filter_where( $where = '' ) {
	// от 30 до 60 дней
	$where .= " AND post_date >= '" . date('Y-m-d', strtotime('-60 days')) . "'" . " AND post_date <= '" . date('Y-m-d', strtotime('-30 days')) . "'";
	return $where;
}

add_filter( 'posts_where', 'filter_where' );
query_posts( $query_string );
remove_filter( 'posts_where', 'filter_where' );

Примеры с параметром date_query

#1. Получим посты между 9 и 17 часами:

$args = array(
	'date_query' => array(
		array(
			'hour'      => 9,
			'compare'   => '>=',
		),
		array(
			'hour'      => 17,
			'compare'   => '<=',
		),
		array(
			'dayofweek' => array( 2, 6 ),
			'compare'   => 'BETWEEN',
		),
	),
	'posts_per_page' => -1,
);
query_posts( $args );

#2. Получим посты за промежуток времени: 1 января по 28 февраля:

$args = array(
	'date_query' => array(
		array(
			'after'     => 'January 1st, 2013',
			'before'    => array(
				'year'  => 2013,
				'month' => 2,
				'day'   => 28,
			),
			'inclusive' => true,
		),
	),
	'posts_per_page' => -1,
);
query_posts( $args );

#3. Получим посты опубликованные год назад, но измененные в последний месяц:

$args = array(
	'date_query' => array(
		array(
			'column' => 'post_date_gmt',
			'before' => '1 year ago',
		),
		array(
			'column' => 'post_modified_gmt',
			'after'  => '1 month ago',
		),
	),
	'posts_per_page' => -1,
);
query_posts( $args );

#4. Получим посты за последние 2 недели, использовав строку '2 weeks ago':

query_posts( array(
	'date_query' => array(
		'after' => '2 weeks ago',
	),
) );

#5. Получим записи за последние 2 месяца, опубликованные в будние дни:

query_posts( array(
	'date_query' => array(
		after => '2 months ago',
		array(
			'dayofweek' => array( 1, 5 ),
			'compare' => 'BETWEEN',
		),
	),
) );

Параметры Отступов

Можно установить отступ от первого поста в результатах запроса. Например, стандартно запрос возвращает 6 постов, а если в тот же запрос добавить параметр offset=1, то будут возвращены 5 постов (первый пост из запроса будет пропущен).

offset(число)

Сколько постов из результатов запроса пропустить.

Пример использования

Пропустим первый/один пост (offset=1) и вернем следующие 5:

query_posts('posts_per_page=5&offset=1');

Параметры Сортировки и порядка

Сортирует и устанавливает направление сортировки.

order(строка)

Направление сортировки по параметру orderby, может быть:

• ASC - по порядку, от меньшего к большему (1, 2, 3; a, b, c).
• DESC - в обратном порядке, от большего к меньшему (3, 2, 1; c, b, a) .

orderby(строка)

Поля по которым можно сортировать посты. Может быть

• none - не сортировать, выводить прям как находиться в БД. равносильно сортировке по ID. С версии 2.8.
• ID - сортировка по ID.
• author - сортировка по ID авторов.
• title - сортировка по заголовку.
• name - по названию поста (ярлык, слаг поста).
• date - сортировка по дате публикации.
• modified - сортировка по дате изменения.
• type - по типу поста (post_type). С версии 4.0
• parent - сортировка по значению поля parent.
• rand - случайный порядок.
• comment_count - сортировка по количеству комментариев. С версии 2.9.
• menu_order - стандартно используется для страниц и вложений. Порядковый номер указывается на странице редактирования поста.
• meta_value Важно: параметр meta_key так же должен быть определен. Заметка: сортировка будет алфавитной и будет не логична, если значения
  произвольных полей числа (будет, например, так 1, 3, 34, 4, 56, 6 и т.д., а не 1, 3, 4, 6, 34, 56).
• meta_value_num - сортировка по произвольным полям значения которых являются числами. С версии 2.8.
• post__in - учитывает порядок указанных ID в параметре post__in.

'orderby' = array()

С версии WordPress 4.0 в orderby можно указывать массив сочетающий в себе оба параметра: orderby и order. Сделано это для сортировки по нескольким колонкам одновременною Синтаксис такой:

'orderby' => array( 'title' => 'DESC', 'menu_order' => 'ASC' )

Примеры

#1 Сортировка по заголовку

query_posts( array ( 'orderby' => 'title', 'order' => 'DESC' ) );

Отсортируем по порядку в меню, а затем по заголовку

query_posts( array ( 'orderby' => 'menu_order title', 'order' => 'DESC' ) );

#2 Выведем один случайный пост:

query_posts( array ( 'orderby' => 'rand', 'posts_per_page' => '1' ) );

#3 Отсортируем посты по количеству комментариев:

query_posts( array( 'orderby' => 'comment_count' ) );

#4 Отсортируем продукты по цене (произвольное поле price):

query_posts( 
	 array ( 'post_type' => 'product', 'orderby' => 'meta_value', 'meta_key' => 'price' ) 
);

#5 Множественная сортировка

Выведем посты отсортированные по двум полям: 'title' и 'menu_order' (title первостепенен):

query_posts( 
	array( 'post_type' => 'page', 'orderby' => 'title menu_order', 'order' => 'ASC' ) 
);

#6 Множественная сортировка с использованием массива (с версии 4.0)

Получим страницы отсортированные по заголовку (title) и номеру меню (menu_order) в разном порядке (ASC/DESC):

query_posts( array( 'orderby' => array( 'title' => 'DESC', 'menu_order' => 'ASC' ) ) );

#7 Сортировка по 'meta_value' для нового типа поста (post_type)

Выведем посты типа 'my_custom_post_type' отсортированные по ключу произвольного поля "age" и отфильтрованные, чтобы показывались только посты со значением поля 3 и 4:

$args = array(
   'post_type' => 'my_custom_post_type',
   'meta_key' => 'age',
   'orderby' => 'meta_value_num',
   'order' => 'ASC',
   'meta_query' => array(
	   array(
		   'key' => 'age',
		   'value' => array(3, 4),
		   'compare' => 'IN',
	   )
   )
 );
 query_posts($args);

Параметры Пагинации

nopaging(логический)

Выключит пагинацию, выведет все посты на одной странице.

posts_per_page(число)

Количество постов на одной странице. Если выставить -1, то будут выведены все посты (без пагинации). С версии 2.1 заменяет параметр showposts. Установите параметр paged, если пагинация не работает, после использования этого параметра.Заметка: если запрос в feed части, WP перезаписывает этот параметр опцией posts_per_rss. Чтобы повлиять на вывод постов в фиде используйте фильтры post_limits или pre_option_posts_per_rss.

posts_per_archive_page(число)

Количество постов для страниц архивов: для страниц, которые удовлетворяют условиям is_archive() или is_search(). Этот параметр перезаписывает параметры "posts_per_page" и "showposts".

offset(число)

Сколько постов пропустить сверху выборки (верхний отступ).
Внимание: Установка этого параметра переписывает/игнорирует параметр "paged" и ломает пагинацию (решение проблемы).

paged(число)

Номер страницы пагинации. Показывает посты, которые в обычном режиме должны были быть показаны на странице пагинации Х. Переписывает параметр posts_per_page

page(число)

Номер для статической домашней страницы. Показывает записи, которые в обычном режиме должны были быть показаны на странице пагинации Х главной статической странице (front page).

ignore_sticky_posts(логический)

Игнорировать (true) прилепленные посты или нет (false). Доступен с версии 3.1. Заменяет параметр caller_get_posts. Заметка: прилепленные посты не будут показываться в начале списка, но они не исключаются и будут выводиться в обычном порядке.

Посты на странице

Выведем 3 поста на странице:

query_posts( 'posts_per_page=3' );

Выведем все посты на странице:

query_posts( 'posts_per_page=-1' );

Выведем все посты и отключим пагинацию:

query_posts( 'nopaging=true' );

Отступы сверху

Выведем посты начиная с четвертого (пропустим первые 3):

query_posts( 'offset=3' ) );

Выведем 5 постов которые идет за тремя последними:

query_posts( array( 'posts_per_page' => 5, 'offset' => 3 ) );

Посты со страницы пагинации Х

Покажем посты со страницы пагинации 6:

query_posts( 'paged=6' );

Посты с текущей страницы

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

query_posts( array( 'paged' => get_query_var( 'paged' ) ) );

Выведем посты с текущей страницы и установим параметр paged в 1, когда переменная не определена на первой странице пагинации:

$paged = (get_query_var('paged')) ? get_query_var('paged') : 1;
query_posts( array( 'paged' => $paged ) );

Заметка: Используйте get_query_var('page'); если нужно получить номер страницы пагинации для статической главной страницы сайта (is_front_page()). Переменная "page" раже содержит номер пагинации на отдельных страницах типа post, когда в контенте используется тег <!--nextpage--> для разбиения контента на страницы.

Вывод текущей страницы пагинации на статической главной странице:

$paged = (get_query_var('page')) ? get_query_var('page') : 1;
query_posts( array( 'paged' => $paged ) );

Прилепленные посты

Выведем все прилепленные посты:

$sticky = get_option( 'sticky_posts' );
query_posts( ('post__in'=>$sticky );

Выведем только первый прилепленный пост:

$sticky = get_option( 'sticky_posts' );
query_posts( 'p=' . $sticky[0] );

Выведем первый прилепленный пост, если такого поста нет, то последний опубликованный:

$args = array(
	'posts_per_page' => 1,
	'post__in'  => get_option( 'sticky_posts' ),
	'ignore_sticky_posts' => 1
);
query_posts( $args );

Выведем первый прилепленный пост, если такого поста нет, то ничего не выводим:

$sticky = get_option( 'sticky_posts' );
$args = array(
	'posts_per_page' => 1,
	'post__in'  => $sticky,
	'ignore_sticky_posts' => 1
);
query_posts( $args );
if ( $sticky[0] ) {
	// формируем вывод...
}

Скрытие прилепленных постов

Исключим все прилепленные посты из запроса:

query_posts( array( 'post__not_in' => get_option( 'sticky_posts' ) ) );

Исключим прилепленные посты из категории. Вернет все посты рубрики, но прилепленные посты не будут сверху, они будут выводится как обычные посты (по дате):

query_posts( array( 'ignore_sticky_posts' => 1, 'posts_per_page' => 3, 'cat' => 6 );

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

$paged = get_query_var( 'paged' ) ? get_query_var( 'paged' ) : 1;
$sticky = get_option( 'sticky_posts' );
$args = array(
	'cat' => 3,
	'ignore_sticky_posts' => 1,
	'post__not_in' => $sticky,
	'paged' => $paged
);
query_posts( $args );

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

s(строка)

поисковая фраза.

Посты найденные по поисковой фразе.

query_posts( 's=keyword' );

Параметры Доступа

Показывает посты если пользователь имеет достаточные права.

perm(строка)

Доступ пользователя.

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

query_posts( 
	  array( 'post_status' => array( 'publish', 'private' ), 'perm' => 'readable' ) 
);

Параметры Кэширования

Не добавляет данные в кэш при выполнении запросов.

cache_results(логический)

Кэшировать ли информацию о посте.

update_post_meta_cache(логический)

Кэшировать ли информацию о мета данных поста.

update_post_term_cache(логический)

Кэшировать ли информацию о привязке поста к терминам и таксономиям.

#1 Выведем 50 постов, но не будет добавлять информацию о постах в кэш:

query_posts( array( 'posts_per_page' => 50, 'cache_results' => false ) );

#2 Выведем 50 постов, но не будем добавлять мета данные поста в кэш

query_posts( array( 'posts_per_page' => 50, 'update_post_meta_cache' => false ) );

#3 Выведем 50 постов, но не будем добавлять в кэш информацию о терминах постов

query_posts( array( 'posts_per_page' => 50, 'update_post_term_cache' => false ) );

Обычно эти функции использовать не нужно - кэш необходим! Однако, такой подход может пригодится в ряде случаев. Например, если нам нужно получить список заголовков постов и не нужна никакая другая информация о постах: ни о таксономиях ни о мета данных. Не загружая эту информацию мы может сохранить время на ненужных SQL запросах.

Параметры Возвращаемых данных

Устанавливает какие данные должен возвращать запрос.

fields(строка/массив)

Какие данные возвращать. По умолчанию возвращаются все.

• ids - вернет массив с ID постов.
• id=>parent - вернет ассоциативный массив [ parent => ID, … ].
• Вставка любых других параметров, вернет все поля (по умолчанию) - массив объектов постов.

Комбинирование параметров

#1. Комбинирование в строке

Вы наверняка заметили, что параметры соединяются между собой символом амперсанд - &, именно этим символом параметры комбинируются (объединяются).

query_posts('cat=3&year=2004');

#2. Комбинирование с переменными

Посты из категории 13 за текущий месяц на главной странице блога:

if (is_home()) {
query_posts($query_string . '&cat=13&monthnum=' . date('n',current_time('timestamp')));
}

#3. Комбинирование массивом

Вернет только 2 поста, из категории 1 и 3, отсортированные в обратном порядке по заголовку:

query_posts( array(
   'category__and'=>array(1,3),
   'posts_per_page'=>2,
   'orderby'=>title,
   'order'=>DESC
));

#4. Записи из категории и с меткой

Вывести все посты из категории 1, имеющие метку apples:

query_posts('cat=1&tag=apples');

Примеры

#1. Чтобы на главной странице блога исключить посты, которые находятся в категории 3, нужно вставить следующий код в файл index.php перед началом Цикла WordPress:

<?php
   if (is_home()) {
	  query_posts("cat=-3");
   }
?>

#1.2. Можно добавить еще несколько категорий к исключению:

<?php
   if (is_home()) {
	  query_posts("cat=-1,-2,-3");
   }
?>

#2. Получим определенный пост (пост с ID = 5):

<?php
// retrieve one post with an ID of 5
query_posts('p=5');
?>

#3. Если нужно использовать функцию "читать дальше" (read more) с новым запросом, то нужно переключить глобальную переменную $more на 0:

<?php
// retrieve one post with an ID of 5
query_posts('p=5');

global $more;
// set $more to 0 in order to only get the first part of the post
$more = 0; 

// the Loop
while (have_posts()) : the_post();
  // the content of the post
  the_content('Read the full post »');
endwhile;
?>

#4. Получаем определенную страницу (страницу 7):

<?php
query_posts('page_id=7');      // получит только страницу с ID 7
?>

или

<?php
query_posts('pagename=o-saite'); // получит только страницу "o-saite"
?>

#4.1. Для дочерних страниц нужно указывать имя родительской страницы и самой дочерней страницы. Имена разделяются слэшем (/). Пример:

<?php
query_posts('pagename=o-saite/avtori'); // получит страницу "avtori", которая является дочерней к "o-saite"
?>

Вставка переменных в параметры запроса

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

#1. Сборка запроса с использованием одинарных кавычек ' ':

<?php
 $categoryvariable=$cat; // задаем переменной $categoryvariable ID текущей категории
 $query= 'cat=' . $categoryvariable. '&orderby=date&order=ASC'; // собираем запрос
 query_posts($query); // запускаем запрос к БД
 ?>

#2. Сборка запроса с использованием двойных кавычек " "

Переменные внутри двойных кавычек интерпретируются PHP как переменные, а не как простой текст):

<?php
$current_month = date('m');
$current_year = date('Y');

query_posts("cat=22&year=$current_year&monthnum=$current_month&order=ASC");
?>
<!-- здесь идет Цикл WordPress -->

#3. Использование глобальной переменной $query_string

Которая содержит в себе базовый запрос для функции query_posts. Если нам нужно не нарушать стандартный вывод постов WordPress (например, на странице категорий), но при этом убрать пагинацию (вывести все посты на одной странице), то мы может дополнить базовый запрос функции query_posts, параметром posts_per_page=-1:

<?php
query_posts($query_string . '&posts_per_page=-1');
while(have_posts()) { the_post();
<!-- здесь идет Цикл WordPress -->
}
?>

Можно измерить значение posts_per_page на конкретное число необходимых нам постов на одной странице. Например, posts_per_page=10 выведет только 10 постов, а если при этом в конце цикла поставить тег шаблона [posts_nav_link()](/functions/posts_nav_link ), то под циклом появится ссылка для перехода к следующим 10-ти постам (ссылка пагинации).

#4. Параметры также можно передать в виде массива

Так они будут более наглядны и читаемы. Например, пример 2 можно записать так:

query_posts(array(
 'cat'      => 22,
 'year'     => $current_year,
 'monthnum' => $current_month,
 'order'    => 'ASC',
));

Как видите тут можно поставить каждую переменную на отдельную строку, а это более понятно и читаемо.

Добавление параметров в запрос

Сохранение базового запроса текущей страницы и добавление в него своих параметров

функция query_posts полностью переписывает запрос, если например, мы напишем query_posts ('cat=1'), то другие параметры запроса, которые используются для текущей страницы (например, сортировка, пагинация и т.д.), будут потеряны и будут выведены посты категории 1 с остальными параметрами по умолчанию. Чтобы сохранить базовые параметры запроса и дополнить/заменить их своими нужно использовать PHP функцию array_merge (объединяет 2 массива в один):

global $wp_query;
query_posts(
	array_merge(
		array('cat' => 1), // это параметр который добавили мы
		$wp_query->query // это массив базового запроса текущей страницы
	)
);

Этот пример по сути тоже самое что и пример 3 (Использование глобальной переменной $query_string), только с использованием массивов.

Код query posts: wp-includes/query.php ^{WP 4.8}

<?php
function query_posts($query) {
	$GLOBALS['wp_query'] = new WP_Query();
	return $GLOBALS['wp_query']->query($query);
}

Cвязанные функции

Из метки: query (запрос)

Еще из раздела: Запросы