Изучаем WP_Query: Действия и фильтры

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

Фильтры, связанные с WP_Query

В кодексе WordPress представлено 16 фильтров, связанных с WP_Query. И сегодня мы будем говорить именно о них.

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

Этот фильтр позволяет изменять количество найденных пунктов без лимита, указанного в WP_Query аргументе posts_per_page.

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

К примеру, если вы объявляете произвольное значение смещения в запросе, WordPress НЕ будет учитывать сдвиг из параметра $wp_query->found_posts. Например, если у вас после смещения из 10 записей имеется еще 45, WordPress будет игнорировать сдвиг, и found_posts все равно выдаст результат из 55 записей.

Фильтруем запрос для получения найденных записей: found_posts_query

Количество найденных записей вычисляется при помощи MySQL-команды SELECT FOUND_ROWS(). Этот фильтр позволяет изменять эту команду, если вам требуется вычислить количество найденных записей каким-нибудь другим образом.

Фильтруем весь SQL-запрос: posts_request

Если вы хотите полностью изменить SQL-запрос, то этот фильтр предназначен как раз для этих целей. Он просто переписывает SQL-запрос, составленный классом WP_Query.

Фильтруем массив, который возвращает запрос: posts_results

Если вам нужно изменить PHP-массив, который WP_Query генерирует с помощью SQL-запроса, то можно воспользоваться этим фильтром. Предлагаю вам наглядный пример работы фильтра.

Учтите, что этот фильтр работает с сырым массивом, который генерируется с помощью SQL-запроса.

Фильтруем массив из полученных записей: the_posts

В отличие от posts_results, фильтр the_posts обрабатывает данные после внутренней обработки массива. Благодаря этому массив будет проверен на наличия неопубликованных или прикрепленных записей. Этот фильтр можно использовать, если вам нужно исключить неопубликованные или прикрепленные записи из массива.

Фильтруем список полей запроса (в том числе поле SELECT) запроса: posts_fields

Команда SQL-запроса SELECT определяет, какие поля из полученной базы данных будут выбраны, а фильтр помогает реализовать это.

Фильтруем команду запроса LIMIT: post_limits

Команда SQL-запроса LIMIT устанавливает ограничения для запроса, а фильтр помогает реализовать это.

Фильтруем команду запроса DISTINCT: posts_distinct

Команда SQL-запроса DISTINCT указывает, что запрос должен вернуть лишь определенные результаты, а фильтр помогает реализовать это. Изначально WP_Query не возвращает какие-то определенные результаты, но при использовании фильтра с функцией, которая возвращает DISTINCT, запрос можно настроить под определенный тип результатов.

Фильтруем часть запроса WHERE: posts_where

Команда SQL-запроса WHERE используется для фильтрации MySQL-операторов SELECT, INSERT, UPDATE или DELETE, а фильтр помогает реализовать это. WP_Query выполняет всю необходимую работу по фильтрации результатов, но вы можете расширить возможности фильтрации при помощи этого фильтра.

Фильтруем часть запроса WHERE после подсчета записей с постраничным выводом: posts_where_paged

Этот фильтр является разновидностью фильтра posts_where, который можно использовать с запросами к записям, состоящим из нескольких страниц.

Фильтруем часть поискового запроса WHERE: posts_search

Еще одна разновидность фильтра posts_where, которую можно использовать для изменения поля запроса WHERE при получении результатов поиска по WordPress.

Фильтруем команду запроса JOIN: posts_join

Команда SQL-запроса JOIN позволяет работать с SQL-командами внутри нескольких таблиц базы данных, а фильтр помогает реализовать это. Это один из самых продвинутых элементов MySQL, поэтому я не рекомендую вам использовать этот фильтр, пока вы не овладеете принципами работы JOIN в MySQL.

Фильтруем команду запроса JOIN после подсчета записей с постраничным выводом: posts_join_paged

Как и posts_where_paged для posts_where, этот фильтр является итерацией фильтра posts_join, который работает с запросами для записей, состоящих из нескольких страниц.

Фильтруем часть запроса ORDER BY: posts_orderby

Команда SQL-запроса ORDER BY отвечает за последовательность запросов, а фильтр помогает реализовать это.

Фильтруем часть запроса GROUP BY: posts_groupby

Команда SQL-запроса GROUP BY позволяет запросу вернуть “сгруппированные” по полям результаты базы данных, а этот фильтр помогает выбрать метод группировки.

Фильтруем все команды запроса: posts_clauses

Если вы хотите работать со всеми частями запроса одновременно, то для этого существует специальный фильтр posts_clauses. Он охватывает команды WHERE, GROUP BY, JOIN, ORDER BY, DISTINCT, SELECT и LIMITS.

WP_Query: связанные действия

Когда мы ознакомились с фильтрами, связанными с WP_Query, давайте перейдем к другому типу хуков – к действиям.

Вмешиваемся в запрос перед его запуском: pre_get_posts

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

<?php
 
function tutsplus_exclude_category( $wp_query ) {
 
    /*
     * Добавляем рубрику в массив исключенных рубрик. В нашем случае, в этом массиве всего одна рубрика – наша. 
     */
    $excluded = array( '-1' );
 
    /*
     * Обратите внимание на этот более опрятный метод написания запросов:
     * 
     * $wp_query->set( 'category__not_in', $excluded );
     */
    set_query_var( 'category__not_in', $excluded );
 
}
 
add_action( 'pre_get_posts', 'tutsplus_exclude_category' );
 
?>

Работаем над парсингом запроса: parse_query

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

Изменяем объект Post: the_post

Термин the_action может немного смутить вас, так как это название используется для хука действия, связанной функции и метода класса WP_Query.

Это действие позволяет изменять объект post сразу после выполнения запроса. Используя это действие, вы можете напрямую изменять выводимые данные. Давайте рассмотрим небольшой пример:

<?php
 
function tutsplus_featured_badge( $post ) {
 
    if ( is_single() && in_category( 'featured' ) ) {
         
        echo '<div class="featured-badge">' . __( 'FEATURED', 'tutsplus' ) . '</div>';
 
    }
 
}
 
add_action( 'the_post', 'tutsplus_featured_badge' );
 
?>

В завершение

Хотите что-нибудь добавить? Сделайте это, оставив свой комментарий ниже. Следующую часть серии мы посвятим свойствам и методам класса WP_Query.

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