Как исправить пагинацию для пользовательских циклов?

Проблема

По умолчанию WordPress использует основной запрос для определения пагинации в любом контексте. Объект основного запроса хранится в глобальной переменной $wp_query, которая также используется для вывода основного цикла запроса:

if ( have_posts() ) : while ( have_posts() ) : the_post();

Когда вы используете пользовательский запрос, вы создаете совершенно отдельный объект запроса:

$custom_query = new WP_Query( $custom_query_args );

И этот запрос выводится через совершенно отдельный цикл:

if ( $custom_query->have_posts() ) : 
    while ( $custom_query->have_posts() ) : 
        $custom_query->the_post();

Но теги пагинации, включая previous_posts_link(), next_posts_link(), posts_nav_link() и paginate_links(), основывают свой вывод на объекте основного запроса $wp_query. Этот основной запрос может быть разбит на страницы, а может и не быть. Например, если текущий контекст — это пользовательский шаблон страницы, основной объект $wp_query будет состоять только из одной записи — той, чей ID соответствует странице, к которой прикреплен пользовательский шаблон.

Если текущий контекст — это архивный индекс какого-либо типа, основной $wp_query может содержать достаточно записей для пагинации, что приводит к следующей части проблемы: для основного объекта $wp_query WordPress передаст параметр paged в запрос, основываясь на URL-параметре paged. При выполнении запроса этот параметр paged будет использоваться для определения, какой набор разбитых на страницы записей вернуть. Если будет нажата ссылка пагинации и загружена следующая страница, ваш пользовательский запрос не будет знать, что пагинация изменилась.

Решение

Передача правильного параметра paged в пользовательский запрос

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

$custom_query_args = array(
    // Пользовательские параметры запроса здесь
);

Вам нужно передать правильный параметр paged в этот массив. Это можно сделать, получив URL-параметр, используемый для определения текущей страницы, через get_query_var():

get_query_var( 'paged' );

Затем вы можете добавить этот параметр в массив аргументов вашего пользовательского запроса:

$custom_query_args['paged'] = get_query_var( 'paged' ) 
    ? get_query_var( 'paged' ) 
    : 1;

Примечание: Если ваша страница — это статическая главная страница, убедитесь, что используете page вместо paged, так как статическая главная страница использует page, а не paged. Вот что должно быть для статической главной страницы:

$custom_query_args['paged'] = get_query_var( 'page' ) 
    ? get_query_var( 'page' ) 
    : 1;

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

Использование объекта пользовательского запроса для функций пагинации

Чтобы функции пагинации выдавали правильный результат — то есть ссылки "предыдущие/следующие/страницы" относительно пользовательского запроса — WordPress нужно заставить распознать пользовательский запрос. Для этого требуется небольшой "хак": замена основного объекта $wp_query на объект пользовательского запроса $custom_query:

Изменение основного объекта запроса

1. Создаем резервную копию основного объекта запроса: $temp_query = $wp_query
2. Обнуляем основной объект запроса: $wp_query = NULL;

3. Заменяем основной объект запроса на пользовательский: $wp_query = $custom_query;

   $temp_query = $wp_query;
   $wp_query   = NULL;
   $wp_query   = $custom_query;
   

Этот "хак" должен быть выполнен перед вызовом любых функций пагинации.

Восстановление основного объекта запроса

После вывода функций пагинации восстановите основной объект запроса:

$wp_query = NULL;
$wp_query = $temp_query;

Исправления для функций пагинации

Функция previous_posts_link() будет работать нормально, независимо от пагинации. Она просто определяет текущую страницу и выводит ссылку на page - 1. Однако для корректной работы next_posts_link() требуется исправление. Это связано с тем, что next_posts_link() использует параметр max_num_pages:

<?php next_posts_link( $label , $max_pages ); ?>

Как и с другими параметрами запроса, по умолчанию функция будет использовать max_num_pages для основного объекта $wp_query. Чтобы заставить next_posts_link() учитывать объект $custom_query, вам нужно передать max_num_pages в функцию. Это значение можно получить из объекта $custom_query: $custom_query->max_num_pages:

<?php next_posts_link( 'Старые записи' , $custom_query->max_num_pages ); ?>

Объединяем все вместе

Ниже приведена базовая структура пользовательского цикла запроса с правильно работающими функциями пагинации:

// Определяем пользовательские параметры запроса
$custom_query_args = array( /* Параметры здесь */ );

// Получаем текущую страницу и добавляем в массив параметров запроса
$custom_query_args['paged'] = get_query_var( 'paged' ) ? get_query_var( 'paged' ) : 1;

// Создаем пользовательский запрос
$custom_query = new WP_Query( $custom_query_args );

// Исправление пагинации
$temp_query = $wp_query;
$wp_query   = NULL;
$wp_query   = $custom_query;

// Вывод пользовательского цикла
if ( $custom_query->have_posts() ) :
    while ( $custom_query->have_posts() ) :
        $custom_query->the_post();
        // Здесь вывод цикла
    endwhile;
endif;
// Сбрасываем данные поста
wp_reset_postdata();

// Пагинация для пользовательского цикла
previous_posts_link( 'Старые записи' );
next_posts_link( 'Новые записи', $custom_query->max_num_pages );

// Восстановление основного объекта запроса
$wp_query = NULL;
$wp_query = $temp_query;

Дополнение: А как насчет query_posts()?

query_posts() для вторичных циклов

Если вы используете query_posts() для вывода пользовательского цикла вместо создания отдельного объекта для пользовательского запроса через WP_Query(), то вы _doing_it_wrong() и столкнетесь с рядом проблем (не меньшей из которых будут проблемы с пагинацией). Первым шагом к их решению будет преобразование неправильного использования query_posts() в правильный вызов WP_Query().

Использование query_posts() для изменения основного цикла

Если вы просто хотите изменить параметры для основного цикла запроса — например, изменить количество записей на странице или исключить категорию — у вас может возникнуть соблазн использовать query_posts(). Но делать этого все равно не стоит. Когда вы используете query_posts(), вы заставляете WordPress заменить основной объект запроса. (WordPress фактически выполняет второй запрос и перезаписывает $wp_query.) Проблема в том, что это происходит слишком поздно в процессе, чтобы обновить пагинацию.

Решение заключается в фильтрации основного запроса до получения записей через хук pre_get_posts.

Вместо добавления этого в файл шаблона категории (category.php):

query_posts( array(
    'posts_per_page' => 5
) );

Добавьте следующее в functions.php:

function wpse120407_pre_get_posts( $query ) {
    // Проверяем, является ли это архивом категории
    // и убеждаемся, что запрос основной
    // а не вторичный (например, меню навигации
    // или виджет последних записей и т.д.
    if ( is_category() && $query->is_main_query() ) {
        // Изменяем количество записей на странице
        $query->set( 'posts_per_page', 5 ); 
    }
}
add_action( 'pre_get_posts', 'wpse120407_pre_get_posts' );

Вместо добавления этого в файл шаблона главной страницы блога (home.php):

query_posts( array(
    'cat' => '-5'
) );

Добавьте следующее в functions.php:

function wpse120407_pre_get_posts( $query ) {
    // Проверяем, является ли это главной страницей блога
    // и убеждаемся, что запрос основной
    // а не вторичный (например, меню навигации
    // или виджет последних записей и т.д.
    if ( is_home() && $query->is_main_query() ) {
        // Исключаем категорию с ID 5
        $query->set( 'category__not_in', array( 5 ) ); 
    }
}
add_action( 'pre_get_posts', 'wpse120407_pre_get_posts' );

Таким образом, WordPress будет использовать уже измененный объект $wp_query при определении пагинации, без необходимости изменять шаблон.

Когда использовать какую функцию

Изучите этот вопрос и ответ и этот вопрос и ответ, чтобы понять, как и когда использовать WP_Query, pre_get_posts и query_posts().