$GLOBALS['wp_the_query'] versus global $wp_query

Te has olvidado de uno, $GLOBALS['wp_query']. Para todos los efectos, $GLOBALS['wp_query'] === $wp_query. Sin embargo, $GLOBALS['wp_query'] es mejor para la legibilidad y debería usarse en lugar de $wp_query, PERO, eso sigue siendo una preferencia personal.

Ahora, en un mundo perfecto donde los unicornios gobiernan el mundo, $GLOBALS['wp_the_query'] === $GLOBALS['wp_query'] === $wp_query. Por defecto, esto debería ser cierto. Si miramos dónde se establecen estos globales (wp-settings.php), verás que el objeto de consulta principal se almacena en $GLOBALS['wp_the_query'] y $GLOBALS['wp_query'] es solo una copia duplicada de $GLOBALS['wp_the_query'].

/**
 * Objeto de consulta de WordPress
 * @global WP_Query $wp_the_query
 * @since 2.0.0
 */
$GLOBALS['wp_the_query'] = new WP_Query();
/**
 * Contiene la referencia a @see $wp_the_query
 * Usa este global para las consultas de WordPress
 * @global WP_Query $wp_query
 * @since 1.5.0
 */
$GLOBALS['wp_query'] = $GLOBALS['wp_the_query'];

La razón de hacerlo de esta manera es porque WordPress vio la llegada de query_posts en la versión 1.5.

function query_posts($query) {
    $GLOBALS['wp_query'] = new WP_Query();
    return $GLOBALS['wp_query']->query($query);
}

Como puedes ver, query_posts establece el objeto de consulta principal a la consulta personalizada actual que se está ejecutando. Esto rompe la integridad del objeto de consulta principal, lo que te da datos incorrectos, por lo que cualquier cosa que dependa del objeto de consulta principal se rompe debido a datos erróneos.

Una forma de contrarrestar esto fue crear otro global para almacenar el objeto de consulta principal, $GLOBALS['wp_the_query'], que se introdujo en la versión 2.0.0. Este nuevo global contiene el objeto de consulta principal y $GLOBALS['wp_query'] es solo una copia. A través de wp_reset_query(), ahora podíamos restablecer $GLOBALS['wp_query'] al objeto de consulta principal original para restaurar su integridad.

Pero este no es un mundo perfecto, y query_posts es el mismísimo diablo. A pesar de miles de advertencias, la gente sigue usando query_posts. Aparte de romper la consulta principal, vuelve a ejecutar la consulta principal, haciéndola mucho más lenta que una consulta personalizada normal con WP_Query. Mucha gente tampoco restablece la consulta de query_posts con wp_reset_query() cuando termina, lo que hace que query_posts sea aún más malvado.

Como no podemos hacer nada al respecto, y no podemos evitar que los plugins y temas usen query_posts y nunca podemos saber si una consulta de query_posts se restableció con wp_reset_query(), necesitamos una copia más confiable del objeto de consulta principal que sepamos que nos dará datos correctos en un 99.99999% de los casos. Ahí es donde $GLOBALS['wp_the_query'] es útil, ya que ningún código relacionado con WordPress puede cambiar su valor (excepto a través de los filtros y acciones dentro del propio WP_Query).

Prueba rápida, ejecuta lo siguiente:

var_dump( $GLOBALS['wp_the_query'] );
var_dump( $GLOBALS['wp_query'] );

query_posts( 's=crap' );


var_dump( $GLOBALS['wp_the_query'] );
var_dump( $GLOBALS['wp_query'] );

y revisa los resultados. $GLOBALS['wp_the_query'] no cambió, y $GLOBALS['wp_query'] sí. Entonces, ¿cuál es más confiable?

Nota final, $GLOBALS['wp_the_query'] NO es un reemplazo para wp_reset_query(). wp_reset_query() debe usarse siempre con query_posts, y query_posts nunca debería usarse.

PARA CONCLUIR

Si necesitas código confiable que casi nunca falle, usa $GLOBALS['wp_the_query']. Si confías y crees en los códigos de plugins y temas y crees que nadie usa query_posts o lo está usando correctamente, usa $GLOBALS['wp_query'] o $wp_query.

EDICIÓN IMPORTANTE

Después de responder preguntas en este sitio durante un par de años, he visto a muchos usuarios usar $wp_query como una variable local, lo que a su vez también rompe el objeto de consulta principal. Esto aumenta aún más la vulnerabilidad de $wp_query.

Por ejemplo, algunas personas hacen esto:

$wp_query = new WP_Query( $args );

que en esencia es exactamente lo mismo que lo que hace query_posts.