WP_Query(), описание класса, параметры

Про класс WP_Query можно сказать в двух словах — нужен для вывода постов, например:

  • из определенной категории и(или) по определенным тегам,
  • за определенный промежуток времени,
  • создание виджетов «Новое на блоге», «Популярные» и «Случайные записи»,
  • возможность отбора и сортировки постов по произвольным полям,
  • расширенный поиск на сайте и и т.д. (возможностей действительно очень много)
примеры использования WP_Query

Циклов на странице может находиться сколько угодно.

Это было небольшое вступление для тех, кто не в курсе.

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

В обоих следующих примерах выводятся ссылки на 5 самых комментируемых записей на блоге:

/*
 * в массиве задаем все необходимые параметры (более подробно о параметрах чуть ниже)
 */
$args = array(
	'posts_per_page' => 5,
	'orderby' => 'comment_count'
);
/*
 * создаем новый объект
 */
$q = new WP_Query($args);
/*
 * проверяем, существуют ли посты по заданным параметрам(необязательно)
 */
if($q->have_posts()) {
	/*
	 * затем запускаем цикл
	 */
	while($q->have_posts()){ $q->the_post();
		/*
		 * выводим например ссылку на каждый пост
		 */
		echo '<a href="' . get_permalink() . '">' . get_the_title() . '</a>';
	}
}
/*
 * восстанавливаем глобальную переменную $post
 */
wp_reset_postdata();

В этом примере мы не трогаем глобальную переменную $post, а также задаем параметры класса в виде строки:

$q = new WP_Query("posts_per_page=5&orderby=comment_count");
if($q->have_posts()) {
	while($q->have_posts()){ $q->next_post();
		$post_id = $q->post->ID;
		echo '<a href="' . get_permalink($post_id) . '">' . get_the_title($post_id) . '</a>';
	}
}

Дальше пойдет описание параметров, ещё есть отдельный пост про методы и свойства.

Параметры класса WP_Query (а также функций query_posts и get_posts)

Авторство

author
(целое число) id автора.

author_name
(строка) «user_nicename» автора, обычно совпадает с логином.

Можно вывести посты сразу нескольких авторов:

$query = new WP_Query( 'author=4,5,8,15' );

Рубрики

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

$q = new WP_Query("cat=-2,-12,-35");

category_name
(строка) ярлык категории (записи из подкатегорий тоже будут учитываться).

$q = new WP_Query("category_name=news,wordpress");

category__and
(массив) отобразить записи, содержащиеся сразу в нескольких категориях одновременно. В массиве указываются ID этих категорий.

$q = new WP_Query(array('category__and' => array(1,4)));

category__in
(массив) отобразить записи, содержащиеся в одной из перечисленных категорий (нужно указать ID), отличается от cat тем, что записи из вложенных рубрик не учитываются.

category__not_in
(массив) исключить записи, содержащиеся в одной из перечисленных категорий.

Метки

tag
(строка) ярлык тега (метки). Можно указать несколько значений через запятую.

$q = new WP_Query("tag=html,css");

Если нужно, чтобы пост содержал каждую из меток, то их надо разделить знаком «+»

$q = new WP_Query("tag=html+css");

tag_id
(целое число) id метки.

$q = new WP_Query("tag_id=15");

tag__and
(массив) отобразить записи, содержащие каждую из этих меток.

$q = new WP_Query(array('tag__and' => array(2,7)));

tag__in
(массив) отобразить записи, содержащие хотя бы одну из перечисленных меток (нужно указать их id).

tag__not_in
(массив) исключить записи, содержащие хотя бы одну из перечисленных меток.

tag_slug__and
(массив) аналогично tag__and, но только вместо id меток надо указать их ярлыки.

tag_slug__in
(массив) аналогично tag__in, но только вместо id меток надо указать ярлыки.

Таксономии

tax_query (доступна с версии 3.1)
(массив массивов) состоит из:

  • taxonomy (строка) — название таксономии,
  • field (строка) — производить выбор по "id" или "slug",
  • terms (целое|строка|массив) — ID(ы) или ярлык(и) таксономии, в зависимости от предыдущего параметра,
  • include_children (логическое) — нужно ли включить вложенные таксономии (по умолчанию — true),
  • operator (строка) — описывает логическое взаимодействие между элементами массива в параметре terms, возможные значения:
    • IN — принадлежит хотя бы одной рубрике (по умолчанию),
    • AND — принадлежит каждой рубрике,
    • NOT IN — не принадлежит ни одной из указанных рубрик;

relation
(строка) описывает логическое взаимодействие между массивами, содержащимися в tax_query, параметры такие же, как и у operator.

Простой пример — будут выведены все статьи из категории GTA Vice City:

$q = new WP_Query( array( 'game' => 'gta_vice_city' ) );

Тот же самый пример с использованием tax_query:

$params = array(
	'tax_query' => array(
		array(
			'taxonomy' => 'game',
			'field' => 'slug',
			'terms' => 'gta_vice_city'
		)
	)
);
$query = new WP_Query( $params );

Дальше идут примеры с использованием нескольких таксономий — в данном случае «game» и «platform».

Простой вариант — выводим посты про GTA Vice City для платформы PC:

$query = new WP_Query( array( 'game' => 'gta_vice_city', 'platform' => 'pc' ) );

Теперь читайте внимательно — выводим посты про GTA III, а также посты про GTA Vice City, при этом исключая платформы с указанными ID:

$args = array(
	'tax_query' => array(
		'relation' => 'AND',
		array(
			'taxonomy' => 'game',
			'field' => 'slug',
			'terms' => array( 'gta_3', 'gta_vice_city' )
		),
		array(
			'taxonomy' => 'platform',
			'field' => 'id',
			'terms' => array( 5, 8 ), // исключаем две платформы, например Android и iOS
			'operator' => 'NOT IN'
		)
	)
);
$query = new WP_Query( $args );

Возможно в этом не сразу удастся разобраться, но на самом деле всё очень просто.

Записи

p
(целое число) ID записи.

$q = new WP_Query("p=123");

name
(строка) ярлык записи.

page_id
(целое число) ID страницы.

Следующие два примера эквивалентны друг другу:

$q = new WP_Query("page_id=2");
$q = new WP_Query("p=2&post_type=page");

pagename
(строка) ярлык страницы.

post_parent
(целое число) вывести все страницы, для которых родительской является страница с указанным id.

$q = new WP_Query("post_parent=9");

Также вложенные страницы можно отобразить при помощи ярлыков, сначала указываете ярлык родительской страницы, потом «/», а потом ярлык вложенной страницы.

$q = new WP_Query("pagename=about-wordpress/functions");

post__in
(массив) какие записи следует включить в цикл.

$q = new WP_Query(array('post__in' => array(3,7,14,15,21)));

post__not_in
(массив) какие записи не следует включать.

Прилепленные записи

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

прилепить пост на главную страницу

ignore_sticky_posts
(логическое) игнорировать приоритет прилепленных постов, по умолчанию — 0 (доступен с версии 3.1).

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

$params = array(
	'posts_per_page' => -1,
	'post__in'  => get_option( 'sticky_posts' ), // массив, содержащий IDы всех прилепленных постов
	'ignore_sticky_posts' => 1
);
 
$q = new WP_Query( $params );

Типы постов

post_type
(строка|массив) тип поста.

  • post — записи, посты (по умолчанию),
  • page — страницы,
  • attachment — вложения, файлы
  • revision — редакции (не черновики),
  • any — все, кроме редакций и постов с параметром exclude_from_search=true,
  • созданный вами тип поста, например game;

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

$q = new WP_Query( array( 'post_type' => array( 'post', 'page' ) ) );

Выводим «книги»:

$q = new WP_Query( 'post_type=book' );

Статусы постов

post_status
(строка) статус записи.

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

Если вам нужно вывести вложения, то не забудьте указать параметр статуса равным any или inherit:

$q = new WP_Query("post_status=any&post_type=attachment");

Форматы записей

Форматы записей выводятся по типу таксономий, например:

$params = array(
	'tax_query' => array( // про tax_query написано чуть выще
		array(
			'taxonomy' => 'post_format', // таксономия форматов
			'field'    => 'slug', // значение этого поля обязательно slug
			'terms'    => array( 'post-format-quote' ), // название одного или нескольких форматов в виде массива
		),
	),
);
$q = new WP_Query( $params );

Параметры постраничной навигации и количества

posts_per_page (доступен с версии 2.1)
(целое число) количество записей, отображаемых на одной странице;

Отобразить сразу все записи:

$q = new WP_Query("posts_per_page=-1");

nopaging
(логическое) запретить постраничную навигацию.

  • false — нет (по умолчанию)
  • true — да
$q = new WP_Query("nopaging=true"); // вывести все посты

paged
(целое число) отобразить записи, находящиеся на определенной странице,

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

$q = new WP_Query("offset=3"); // начинаем с 4-й записи

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

orderby
(строка) сортировать по:

  • none — не сортировать,
  • ID — по id,
  • author — по имени автора,
  • title — по заголовку,
  • date — по дате публикации (по умолчанию),
  • modified — по дате последнего изменения,
  • parent — по id родительских страниц,
  • rand — случайным образом,
  • comment_count — по количеству комментариев (начиная с версии 2.9),
  • menu_order — сортировать по указанному порядку, по умолчанию в WordPress уже есть инструменты для установки собственного порядка страниц и вложений:
    указываем порядковый номер в метабоксе атрибутов страницы
    сортировка изображений, вложенных в пост
  • meta_value — по значению мета-данных поста (произвольного поля), при этом в цикле должен присутствовать параметр meta_key; используется только для сортировки строковых значений,
  • meta_value_num — по значению произвольного поля, для сортировки чисел,
  • post__in — использовать порядок, заданный в параметре post__in (с версии 3.5);

order
(строка) порядок сортировки.

  • ASC — по возрастанию (1, 2, 3; a, b, c),
  • DESC — по убыванию (3, 2, 1; c, b, a) (по умолчанию);

Дата и время

year
(целое число) год публикации,

monthnum
(целое число) месяц публикации (от 1 до 12),

w
(целое число) неделя публикации (от 0 до 53),

day
(целое число) день публикации (от 1 до 31),

hour
(целое число) час (от 0 до 23),

minute
(целое число) минута (от 0 до 60),

second
(целое число) секунда (от 0 до 60);

Все посты, опубликованные 20 декабря 2011:

$q = new WP_Query("year=2011monthnum=12&day=20");

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

В WP 3.7 появился также очень удобный date_query.

Произвольные поля

Про произвольные поля читайте подробнее тут.

meta_key
(строка) название произвольного поля,

meta_value
(строка) значение произвольного поля,

meta_value_num
(число) значение произвольного поля,

meta_compare
(строка) оператор сопоставления значений произвольного поля, может принимать значения: '!=', '>', '>=', '<' или '<='. По умолчанию '=';

Отобразить все записи, в которых значение произвольного поля color равно blue.

$q = new WP_Query("meta_key=color&meta_value=blue");

Отобразить записи, в которых значение любого произвольного поля равно blue.

$q = new WP_Query("meta_value=blue");

А в этом варианте выводятся посты, у которых значение произвольного поля color не равно red.

$q = new WP_Query(array( 'meta_key' => 'color', 'meta_value' => 'red', 'meta_compare' => '!=' ));

Начиная с версии WordPress 3.1 параметры произвольных полей можно задавать через массив meta_query.

meta_query
(массив массивов) состоит из:

  • key (строка) — название произвольного поля,
  • value (строка|массив) — значение произвольного поля (параметр может быть опущен, если для сравнения используются операторы 'EXISTS' или 'NOT EXISTS' — доступны, начиная с 3.5 )
  • compare (строка) — оператор сопоставления, возможные значения: '=' (по умолчанию), '!=', '>', '>=', '<', '<=', 'LIKE', 'NOT LIKE', 'IN', 'NOT IN', 'BETWEEN', 'NOT BETWEEN', 'EXISTS' и 'NOT EXISTS',
  • type (строка) — тип данных значения произвольного поля, например 'NUMERIC', 'BINARY', 'CHAR' (по умолчанию), 'DATE', 'DATETIME', 'DECIMAL', 'SIGNED', 'TIME', 'UNSIGNED'.

relation
(строка) описывает логическое взаимодействие между массивами, содержащимися в meta_query.

В этом примере выводим анкеты людей, которые разбираются в WordPress или DLE, и им от 18 до 25 лет.

$args = array(
	'post_type' => 'resume',
	'meta_query' => array(
		'relation' => 'AND',
		array(
			'key' => 'cms',
			'value' => array( 'wordpress', 'dle' ),
			'compare' => 'IN'
		),
		array(
			'key' => 'age',
			'value' => array( 18, 25 ),
			'type' => 'numeric',
			'compare' => 'BETWEEN'
		)
	)
);
$query = new WP_Query( $args );

По meta_query конечно можно ещё кучу примеров написать, если у вас есть вопросы или что-то не работает — спрашивайте в комментариях, отвечу всем.

Другие параметры

fields
(строка) в каком виде выводить результат:

  • ids — массив составленный из ID элементов (постов), кстати посмотреть на вид самих массивов вы можете через функцию print_r() или заглянув в пост про get_terms(),
  • id=>parent — ассоциативный массив состоящих из ID элементов и ID их родителей, при этом, если родительского элемента не существует, то возвращается 0, пример:
    $q = new WP_Query('post_type=page&posts_per_page=-1&fields=id=>parent');
    print_r($q);
    /*
    Результат примерно такой:
    Array ( [1] => 0 [4] => 0 [11] => 4 )
    */
  • по умолчанию выводится массив объектов постов;

s
(строка) поиск постов по указанному ключевому слову, например:

$q = new WP_Query( 's=wordpress' );

Аналог WP_Query для WordPress Multisite

Миша Рудрастых Разработчик WordPress WooCommerce

Миша Рудрастых

Впервые познакомился с WordPress в 2009 году, и после двух лет мучений с Joomla и самописными движками это был просто бальзам на душу. С 2014 года меня можно встретить на WordCamp — официальной конфе по WP в Москве, иногда там выступаю. Также в настоящее время веду курсы по WordPress в Epic Skills в Питере.

Смотрите также