WP_Query::is_main_query()

Définition : WP_Query::is_main_query() est une méthode qui vérifie si une instance WP_Query correspond à la requête principale WordPress. Elle aide les extensions à distinguer cette requête des recherches secondaires créées pour d’autres affichages.

Terminologie

Appellation / équivalent : WP_Query::is_main_query — vérification de la requête principale

Autres appellations : Détection de la requête principale, Main Query

Comprendre le fonctionnement

WordPress conserve une référence à la requête principale. La méthode compare l’instance examinée à cette référence et renvoie un booléen. Elle est particulièrement utile dans les callbacks recevant une instance WP_Query, car elle permet de cibler précisément les modifications apportées aux paramètres.

La fonction globale is_main_query() n’est pas équivalente dans tous les contextes : dans un callback pre_get_posts qui reçoit un objet de requête, il faut privilégier $query->is_main_query(). Le contrôle du contexte d’administration reste également nécessaire avant de modifier le nombre de publications ou les filtres de recherche.

Exemple concret

Une extension modifie uniquement la pagination de l’archive principale, sans toucher à une liste secondaire présente dans la barre latérale.

Exemple de code commenté

<?php
// Exemple de callback dans un plugin, sans modifier l'administration.
add_action( 'pre_get_posts', function ( $query ) {
    if ( is_admin() || ! $query->is_main_query() ) {
        return;
    }
    if ( $query->is_home() ) {
        $query->set( 'posts_per_page', 8 );
    }
} );