¿Cómo arreglar la paginación para bucles personalizados?

El Problema

Por defecto, en cualquier contexto, WordPress utiliza la consulta principal para determinar la paginación. El objeto de la consulta principal se almacena en la variable global $wp_query, que también se utiliza para mostrar el bucle de la consulta principal:

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

Cuando utilizas una consulta personalizada, creas un objeto de consulta completamente separado:

$custom_query = new WP_Query( $custom_query_args );

Y esa consulta se muestra mediante un bucle completamente separado:

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

Pero las etiquetas de plantilla de paginación, incluyendo previous_posts_link(), next_posts_link(), posts_nav_link() y paginate_links(), basan su salida en el objeto de consulta principal, $wp_query. Esa consulta principal puede o no estar paginada. Si el contexto actual es una plantilla de página personalizada, por ejemplo, el objeto principal $wp_query consistirá en solo una sola publicación - la del ID de la página a la que está asignada la plantilla de página personalizada.

Si el contexto actual es un índice de archivo de algún tipo, la consulta principal $wp_query puede consistir en suficientes publicaciones para causar paginación, lo que lleva a la siguiente parte del problema: para el objeto principal $wp_query, WordPress pasará un parámetro paged a la consulta, basado en la variable de consulta URL paged. Cuando se recupera la consulta, ese parámetro paged se usará para determinar qué conjunto de publicaciones paginadas devolver. Si se hace clic en un enlace de paginación mostrado y se carga la siguiente página, tu consulta personalizada no tendrá forma de saber que la paginación ha cambiado.

La Solución

Pasar el Parámetro Paged Correcto a la Consulta Personalizada

Suponiendo que la consulta personalizada utiliza un array de argumentos:

$custom_query_args = array(
    // Parámetros de consulta personalizada van aquí
);

Necesitarás pasar el parámetro paged correcto al array. Puedes hacerlo obteniendo la variable de consulta URL utilizada para determinar la página actual, a través de get_query_var():

get_query_var( 'paged' );

Luego puedes agregar ese parámetro a tu array de argumentos de consulta personalizada:

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

Nota: Si tu página es una página de inicio estática, asegúrate de usar page en lugar de paged, ya que una página de inicio estática utiliza page y no paged. Esto es lo que deberías tener para una página de inicio estática:

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

Ahora, cuando se recupere la consulta personalizada, se devolverá el conjunto correcto de publicaciones paginadas.

Usar el Objeto de Consulta Personalizada para Funciones de Paginación

Para que las funciones de paginación generen la salida correcta - es decir, enlaces anterior/siguiente/página relativos a la consulta personalizada - WordPress necesita ser forzado a reconocer la consulta personalizada. Esto requiere un pequeño "hack": reemplazar el objeto principal $wp_query con el objeto de consulta personalizada, $custom_query:

Modificar el objeto de consulta principal

1. Haz una copia de seguridad del objeto de consulta principal: $temp_query = $wp_query
2. Anula el objeto de consulta principal: $wp_query = NULL;

3. Intercambia la consulta personalizada en el objeto de consulta principal: $wp_query = $custom_query;

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

Este "hack" debe hacerse antes de llamar a cualquier función de paginación

Restablecer el objeto de consulta principal

Una vez que se hayan mostrado las funciones de paginación, restablece el objeto de consulta principal:

$wp_query = NULL;
$wp_query = $temp_query;

Correcciones en las Funciones de Paginación

La función previous_posts_link() funcionará normalmente, independientemente de la paginación. Simplemente determina la página actual y luego muestra el enlace para página - 1. Sin embargo, se requiere una corrección para que next_posts_link() se muestre correctamente. Esto se debe a que next_posts_link() utiliza el parámetro max_num_pages:

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

Al igual que otros parámetros de consulta, por defecto la función utilizará max_num_pages para el objeto principal $wp_query. Para forzar a next_posts_link() a tener en cuenta el objeto $custom_query, necesitarás pasar max_num_pages a la función. Puedes obtener este valor del objeto $custom_query: $custom_query->max_num_pages:

<?php next_posts_link( 'Publicaciones Antiguas' , $custom_query->max_num_pages ); ?>

Juntando Todo

Lo siguiente es una estructura básica de un bucle de consulta personalizada con funciones de paginación que funcionan correctamente:

// Definir parámetros de consulta personalizada
$custom_query_args = array( /* Parámetros van aquí */ );

// Obtener página actual y agregar al array de parámetros de consulta personalizada
$custom_query_args['paged'] = get_query_var( 'paged' ) ? get_query_var( 'paged' ) : 1;

// Instanciar consulta personalizada
$custom_query = new WP_Query( $custom_query_args );

// Corrección de paginación
$temp_query = $wp_query;
$wp_query   = NULL;
$wp_query   = $custom_query;

// Mostrar bucle de consulta personalizada
if ( $custom_query->have_posts() ) :
    while ( $custom_query->have_posts() ) :
        $custom_query->the_post();
        // Salida del bucle va aquí
    endwhile;
endif;
// Restablecer datos de publicación
wp_reset_postdata();

// Paginación del bucle de consulta personalizada
previous_posts_link( 'Publicaciones Antiguas' );
next_posts_link( 'Publicaciones Nuevas', $custom_query->max_num_pages );

// Restablecer objeto de consulta principal
$wp_query = NULL;
$wp_query = $temp_query;

Adenda: ¿Qué Pasa con query_posts()?

query_posts() para Bucles Secundarios

Si estás usando query_posts() para mostrar un bucle personalizado, en lugar de instanciar un objeto separado para la consulta personalizada mediante WP_Query(), entonces estás _doing_it_wrong(), y te encontrarás con varios problemas (no el menor de los cuales serán problemas de paginación). El primer paso para resolver esos problemas será convertir el uso incorrecto de query_posts() a una llamada adecuada de WP_Query().

Usar query_posts() para Modificar el Bucle Principal

Si solo quieres modificar los parámetros para la consulta del bucle principal - como cambiar las publicaciones por página o excluir una categoría - podrías sentirte tentado a usar query_posts(). Pero aun así no deberías. Cuando usas query_posts(), obligas a WordPress a reemplazar el objeto de consulta principal. (WordPress en realidad hace una segunda consulta y sobrescribe $wp_query). El problema, sin embargo, es que hace este reemplazo demasiado tarde en el proceso como para actualizar la paginación.

La solución es filtrar la consulta principal antes de que se recuperen las publicaciones, mediante el hook pre_get_posts.

En lugar de agregar esto al archivo de plantilla de categoría (category.php):

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

Agrega lo siguiente a functions.php:

function wpse120407_pre_get_posts( $query ) {
    // Comprobar índice de archivo de categoría
    // y asegurarse de que la consulta es la consulta principal
    // y no una consulta secundaria (como un menú de navegación
    // o salida de widget de publicaciones recientes, etc.
    if ( is_category() && $query->is_main_query() ) {
        // Modificar publicaciones por página
        $query->set( 'posts_per_page', 5 ); 
    }
}
add_action( 'pre_get_posts', 'wpse120407_pre_get_posts' );

En lugar de agregar esto al archivo de plantilla de índice de publicaciones del blog (home.php):

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

Agrega lo siguiente a functions.php:

function wpse120407_pre_get_posts( $query ) {
    // Comprobar índice principal de publicaciones del blog
    // y asegurarse de que la consulta es la consulta principal
    // y no una consulta secundaria (como un menú de navegación
    // o salida de widget de publicaciones recientes, etc.
    if ( is_home() && $query->is_main_query() ) {
        // Excluir categoría ID 5
        $query->set( 'category__not_in', array( 5 ) ); 
    }
}
add_action( 'pre_get_posts', 'wpse120407_pre_get_posts' );

De esta manera, WordPress utilizará el objeto $wp_query ya modificado al determinar la paginación, sin necesidad de modificar la plantilla.

Cuándo Usar Qué Función

Investiga esta pregunta y respuesta y esta pregunta y respuesta para entender cómo y cuándo usar WP_Query, pre_get_posts y query_posts().