Que ce soit pour afficher la page d’accueil, une recherche ou une liste triée par un plugin, tout affichage de contenus WordPress passe, en coulisses, par une seule et même classe chargée de transformer des critères en résultats SQL.
Fonctionnement dans WordPress
Une instance de WP_Query accepte un tableau d’arguments très riche — type de contenu, taxonomie, méta-requête, tri, pagination — et expose ensuite des méthodes comme have_posts() et the_post() pour parcourir les résultats, exactement comme la Boucle standard le fait avec l’objet global $wp_query. C’est cette même classe qui, en interne, construit aussi bien la requête principale que n’importe quelle requête personnalisée créée dans un gabarit.
Exemple
$requete = new WP_Query( array(
'post_type' => 'produit',
'meta_key' => 'en_promotion',
'meta_value' => '1',
) );Bon à savoir
Une requête basée sur des méta-clés peut devenir très coûteuse sur un grand catalogue, la table wp_postmeta n’étant pas indexée pour ce type de recherche ; au-delà d’un certain volume, une taxonomie ou une variable de requête dédiée offre de meilleures performances qu’une méta-requête.
Bon à savoir
La propriété found_posts de l’objet retourné indique le nombre total de résultats correspondant aux critères, indépendamment de la pagination appliquée ; elle sert notamment à calculer le nombre de pages via max_num_pages, utilisé par les fonctions de pagination du thème.
Deux instances de WP_Query peuvent coexister sans interférer l’une avec l’autre tant que chacune conserve son propre pointeur d’itération ; c’est justement l’absence de cette isolation qui rend indispensable la fonction wp_reset_postdata() après une requête personnalisée exécutée en parallèle de la requête principale.