Cuándo usar WP_query(), query_posts() y pre_get_posts

Existen dos contextos diferentes para los bucles (loops):

• El bucle principal que ocurre basado en la solicitud URL y se procesa antes de cargar las plantillas
• Los bucles secundarios que ocurren de cualquier otra manera, llamados desde archivos de plantilla o de otro modo

El problema con query_posts() es que es un bucle secundario que intenta ser el principal y falla miserablemente. Por lo tanto, olvida que existe.

Para modificar el bucle principal

• no uses query_posts()
• usa el filtro pre_get_posts con la verificación $query->is_main_query()
• alternativamente usa el filtro request (un poco demasiado brusco, por lo que lo anterior es mejor)

Para ejecutar un bucle secundario

Usa new WP_Query o get_posts() que son prácticamente intercambiables (el último es un envoltorio ligero del primero).

Para limpiar

Usa wp_reset_query() si utilizaste query_posts() o manipulaste directamente la variable global $wp_query - por lo que casi nunca lo necesitarás.

Usa wp_reset_postdata() si utilizaste the_post() o setup_postdata() o manipulaste la variable global $post y necesitas restaurar el estado inicial de las cosas relacionadas con el post.

Existen escenarios legítimos para usar query_posts($query), por ejemplo:

1. Quieres mostrar una lista de entradas o entradas de tipos de contenido personalizados en una página (usando una plantilla de página)

2. Quieres que la paginación de esas entradas funcione

¿Por qué querrías mostrarlo en una página en lugar de usar una plantilla de archivo?

1. Es más intuitivo para un administrador (¿tu cliente?) - pueden ver la página en 'Páginas'

2. Es mejor para agregarlo a los menús (sin la página, tendrían que agregar la URL directamente)

3. Si deseas mostrar contenido adicional (texto, imagen destacada o cualquier meta contenido personalizado) en la plantilla, puedes obtenerlo fácilmente de la página (y también tiene más sentido para el cliente). Si usaras una plantilla de archivo, necesitarías codificar el contenido adicional o usar, por ejemplo, opciones del tema/plugin (lo que lo hace menos intuitivo para el cliente)

Aquí tienes un ejemplo de código simplificado (que estaría en tu plantilla de página - por ejemplo, page-page-of-posts.php):

/**
 * Nombre de la plantilla: Página de entradas
 */

while(have_posts()) { // bucle principal original - contenido de la página
  the_post();
  the_title(); // título de la página
  the_content(); // contenido de la página
  // etc...
}

// ahora mostramos la lista de nuestras entradas de tipo de contenido personalizado

// primero obtenemos los parámetros de paginación
$paged = 1;
if(get_query_var('paged')) {
  $paged = get_query_var('paged');
} elseif(get_query_var('page')) {
  $paged = get_query_var('page');
}

// consultamos las entradas y reemplazamos la consulta principal (página) con esta (para que la paginación funcione)
query_posts(array('post_type' => 'my_post_type', 'post_status' => 'publish', 'paged' => $paged));

// paginación
next_posts_link();
previous_posts_link();

// bucle
while(have_posts()) {
  the_post();
  the_title(); // título de tu entrada de tipo de contenido personalizado
  the_content(); // contenido de tu entrada de tipo de contenido personalizado
}

wp_reset_query(); // establece la consulta principal (global $wp_query) a la consulta original de la página (la obtiene de la variable global $wp_the_query) y restablece los datos de la entrada

// Entonces, ahora podemos mostrar el contenido relacionado con la página nuevamente (si lo deseamos)
while(have_posts()) { // bucle principal original - contenido de la página
  the_post();
  the_title(); // título de la página
  the_content(); // contenido de la página
  // etc...
}

Ahora, para ser completamente claros, también podríamos evitar usar query_posts() aquí y usar WP_Query en su lugar - así:

// ...

global $wp_query;
$wp_query = new WP_Query(array('tus parámetros de consulta aquí')); // establece la nueva consulta personalizada como consulta principal

// tu bucle de tipo de contenido personalizado aquí

wp_reset_query();

// ...

Pero, ¿por qué haríamos eso cuando tenemos una función tan pequeña y agradable disponible para ello?

Modifico la consulta de WordPress desde functions.php:

//desafortunadamente, la condición "IS_PAGE" no funciona en pre_get_posts (es un comportamiento de WORDPRESS)
//por lo que puedes usar `add_filter('posts_where', ....);`    O   modificar la consulta de "PAGE" directamente en el archivo de plantilla

add_action( 'pre_get_posts', 'myFunction' );
function myFunction($query) {
    if ( ! is_admin() && $query->is_main_query() )  {
        if (  $query->is_category ) {
            $query->set( 'post_type', array( 'post', 'page', 'my_postType' ) );
            add_filter( 'posts_where' , 'MyFilterFunction_1' ) && $GLOBALS['call_ok']=1; 
        }
    }
}
function MyFilterFunction_1($where) {
   return (empty($GLOBALS['call_ok']) || !($GLOBALS['call_ok']=false)  ? $where :  $where . " AND ({$GLOBALS['wpdb']->posts}.post_name NOT LIKE 'Journal%')"; 
}

Solo para esbozar algunas mejoras a la respuesta aceptada ya que WordPress ha evolucionado con el tiempo y algunas cosas son diferentes ahora (cinco años después):

pre_get_posts es un filtro, para alterar cualquier consulta. Se usa más comúnmente para alterar solo la 'consulta principal':

En realidad es un action hook. No es un filtro, y afectará a cualquier consulta.

La consulta principal aparece en tus plantillas como:

if( have_posts() ):
    while( have_posts() ): the_post();
       //El loop
    endwhile;
endif;

En realidad, esto tampoco es cierto. La función have_posts itera el objeto global $wp_query que no está relacionado únicamente con la consulta principal. global $wp_query; puede ser alterado también con consultas secundarias.

function have_posts() {
    global $wp_query;
    return $wp_query->have_posts();
}

get_posts()

Esto es esencialmente un envoltorio para una instancia separada de un objeto WP_Query.

En realidad, actualmente WP_Query es una clase, por lo que tenemos una instancia de una clase.

Para concluir: En el momento en que @StephenHarris escribió esto, muy probablemente todo era cierto, pero con el tiempo las cosas en WordPress han cambiado.