Изучаем WP_Query: Связанные функции

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

Задействуем всю мощь WP_Query при помощи функций, действий и фильтров

WP_Query – один из лучших примеров схемы MVC (Model-view-controller или «модель-представление-контроллер). Он многофункционален, расширяем, и очень прост в использовании.

Дополнительно в ядре WordPress реализованы функции и хуки для работы с этим классом. В нашем сегодняшнем руководстве мы познакомимся с его функциями.

Функции присущие WP_Query

В WordPress имеется 13 функций, позволяющих полноценно работать с классом WP_Query.

Получение переменных запросов: get_query_var()

Извлекает из объекта $ WP_Query значение переменной запроса. У функции есть два параметра: первый – это переменная, которая возвращает значение, а второй – значение по умолчанию, которое возвращается при неустановленной переменной:

<?php

$paged = get_query_var( 'paged', 1 );

?>

Изменение основного цикла: query_posts()

query_posts() – эта функция изменяет основной запрос и запускает новый. После каждого ее использования вам нужно будет запускать wp_reset_query():

<?php

query_posts( 'category_name=news' );

?>

Эту функцию из ядра WordPress часто используют ненадлежащим образом. Не следует использовать ее для создания вторичных запросов, вместо этого можно использовать класс WP_Query или функцию get_posts() для изменения основного запроса.

Для этого лучше использовать функцию pre_get_posts, которую мы обсудим чуть позже. Даже кодекс WordPress не рекомендует использовать эту функцию.

Получение отдельной записи: get_post()

get_post() – это функция, с помощью которой вы можете извлечь любую отдельную запись. Она принимает три необязательных параметра:

  • post ID (по умолчанию ID текущей записи);
  • тип результата, который вы можете получить: OBJECT, ARRAY_A (ассоциативный массив) или ARRAY_N (числовой массив);
  • способ фильтрации результатов. Стандартное значение ‘raw’, то есть, результаты не будут фильтроваться до тех пор, пока вы не примените значения ‘edit‘, ‘display‘, ‘attribute‘ или ‘js‘:
<?php

$first_post = get_post( 1, ARRAY_A );
$post_title = $first_post[ 'post_title' ];

?>

Сохраняем запросы в массивы: get_posts()

Функция get_posts() позволяет выполнить запросы и сохранить их как массивы. Здесь нужно использовать те же аргументы, которые вы используете в WP_Query. Это один из лучших и эффективных способов создания списка записей:

<?php

$args = array(
    'category_name' => 'news',
    'order' => 'ASC',
    'orderby' => 'post_title',
    'posts_per_page' => -1
);

// Возвращаем массив со всеми записями из рубрики “News”.
$all_posts_list = get_posts( $args );

?>

Эту функцию можно использовать для запуска «вторичных запросов», кодекс WordPress рекомендует при создании множественных циклов использовать WP_Query и get_posts() для извлечения списка записей. Основное отличие заключается в том, что WP_Query делает больше запросов к базе данных (данные записи, мета-данные, данные об авторе, а также комментарии), а get_posts() запрашивает лишь данные записи (post data).

Получаем страницы: get_pages()

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

<?php

$args = array(
    'sort_order' => 'ASC',
    'sort_column' => 'post_title',
    'hierarchical' => 1,
    'exclude' => '',
    'include' => '',
    'meta_key' => '',
    'meta_value' => '',
    'authors' => '',
    'child_of' => 0,
    'parent' => -1,
    'exclude_tree' => '',
    'number' => '',
    'offset' => 0,
    'post_type' => 'page',
    'post_status' => 'publish'
);

$pages = get_pages( $args );

?>

Функция принимает аргументы, похожие на аргументы WP_Query:

  • sort_order: сортировать страницы в возрастающем (asc) или убывающем (desc) порядке;
  • sort_column: как сортировать страницы. Допустимы значения: post_title, menu_order, post_date, post_modified, ID, post_author, и post_name;
  • hierarchical: включена иерархия страниц (1) или нет (0);
  • exclude: список через запятую или указание массива ID страниц, которые следует исключить из вывода;
  • include: список через запятую или указание массива ID страниц, которые нужно вывести, не показывая все остальное;
  • meta_key: при использовании с аргументом meta_value, выводятся страницы только с определенным мета-ключом и значением;
  • meta_value: при использовании с аргументом meta_key, выводятся страницы только с определенным мета-ключом и значением;
  • authors: список ID авторов через запятую;
  • child_of: ID страницы, дочерние страницы которой будут выведены в списке;
  • parent: список страниц с указанным родительским ID. Чтобы этот аргумент вступил в силу, значение hierarchical должно быть выставлено на 0;
  • exclude_tree: список через запятую или массив ID страниц, которые нужно исключить вместе с их дочерними страницами;
  • number: количество страниц, которое будет выведено;
  • offset: количество страниц, которые будут пропущены в самом начале списка;
  • post_type: тип записей для запроса. По умолчанию используется тип простых страниц page;
  • post_status: список типов статуса записей через запятую, которые будут включены в выдачу.

Проверяем, выдает ли запрос записи: have_posts()

Не принимая никаких параметров, эта функция возвращает значение true при наличии записей, и false при их отсутствии:

<?php

if ( have_posts() ) {

    // Успешно.

} else {

    // Ошибка.

}

?>

Работаем с циклами: the_post()

В кодексе говорится, что эта функция «создает итерацию индекса записи в цикле». Она делает следующее:

  • Извлекает следующую запись из запроса;
  • Устанавливает данные $post;
  • Устанавливает параметр in_the_loop в значение true:
<?php

if ( have_posts() ) {

    while ( have_posts() ) {

        the_post();

        the_title();

        the_content();

    }

}

?>

Настройка переменной $post: setup_postdata()

Эта функция устанавливает данные глобальной записи. Давайте посмотрим, что об этом говорится в кодексе WordPress:

setup_postdata() заполняет глобальные переменные id, $authordata, $currentday, $currentmonth, $page, $pages, $multipage, $more, $numpages. Они нужны для корректной работы тегов шаблонов в контексте текущей записи. Она не задает глобальную переменную $post, а принимает ее:

<?php

global $post;

setup_postdata( $post );

?>

Очищаем текущий цикл: rewind_posts()

Эта функция “перематывает” цикл в его начало:

<?php

// После цикла.
rewind_posts();

?>

Сбрасываем $post: wp_reset_postdata()

Эта функция сбрасывает глобальную переменную $post к первой записи в основном запросе. Лучше использовать ее после вторичного запроса:

<?php

// После вторичного запроса.
wp_reset_postdata();

?>

Сбрасываем запрос: wp_reset_query()

Эту функцию можно использовать, если основной запрос был изменен при помощи функции query_posts() или действия pre_get_posts. Она поможет сбросить запрос, и вернуть его в первоначальное состояние:

<?php

// После того как основной запрос был изменен.
wp_reset_query();

?>

Проверяем, является ли текущий запрос основным: is_main_query()

Это условный тег, который возвращает значение true, если текущий запрос является основным, или значение false, если он таковым не является:

<?php

if ( is_main_query() ) {

    // Успешно.

} else {

    // Ошибка.

}

?>

Проверяем, находимся ли мы внутри цикла: in_the_loop()

Еще один условный тег, который возвращает значение true, если ваш код работает внутри цикла:

<?php

if ( in_the_loop() ) {

    // Успешно.

} else {

    // Ошибка.

}

?>

Завершение третьей части

Теперь вы знакомы со всеми функциями, связанными с WP_Query. Не пропускайте следующие статьи из серии, посвященной изучению этого класса.

Если вам есть что добавить, обязательно напишите об этом в своих комментариях!

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