# WP_Query

> WP_Query est la classe PHP centrale de WordPress qui construit et exécute les requêtes de récupération de contenus, principales comme personnalisées.

- Auteur : Clément Hadrot
- Publié le : 2026-09-25
- Mis à jour le : 2026-09-25
- URL : https://wpmoderne.dev.wordpress-developpement.fr/lexique/wp-query/

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.