Formation « Développer un thème WordPress sur mesure »

Créer des requêtes personnalisées avec la WP Query

Lecture : 8 minutes • 20

La WP Query est une classe du coeur de WordPress que l’on va pouvoir utiliser pour lancer des requêtes personnalisées. Son but ? Récupérer les données de notre choix, comme par exemple les derniers articles ou une page en particulier, grâce à différents critères mis à notre disposition.

Si vous êtes dans le cas où vous avez une page standard, dans laquelle vous aimeriez faire une zone qui afficherait les 3 derniers articles, alors la WP Query est faite pour vous !

Qu’est-ce que la WP Query ?

Voici ce que je peux vous dire de la WP Query :

WP Query

Définition

La WP Query est une classe PHP WordPress permettant d’effectuer une requête pour récupérer des données spécifiques du CMS sans écrire une requête SQL. En fournissant des paramètres parmis plus de 100 proposés, il est possible de demander n’importe quelles publications triées selon certains critères comme l’auteur, la date de publication, le nombre de commentaires, le statut de publication, la catégorie et permet même de choisir le nombre de résultats et leur ordre d’affichage. La WP Query est tout d’abord utilisée par le coeur de WordPress lorsqu’il affiche les pages, mais elle est également disponible aux développeurs pour créer leurs propres requêtes complémentaires.

Traduction : Requête WP

Ce qu’il faut retenir, c’est que cette WP Query est un élément essentiel de WordPress, utilisée en interne, mais également disponible pour les développeurs !

Et ça tombe bien, car on en aura régulièrement besoin dans nos thèmes.

Dans quels cas utiliser la WP Query dans son thème ?

Imaginons que vous concevez une belle page d’accueil, avec plusieurs sections, et qu’à un moment, vous souhaitez afficher les 3 derniers articles du blog :

Maquette d'un site avec plusieurs sections (en vert) et au milieu la liste des 3 derniers articles (en jaune).
En plein milieu de ma page, je souhaite afficher la liste des 3 derniers articles (en jaune)

Les sections en vert représentent le contenu de la page. En plein milieu, on voudrait insérer une section (en jaune) affichant les 3 derniers articles parus.

Nativement, WordPress ne vous permet pas de le faire. Soit vous affichez les derniers articles seulement, en plaçant le blog en page d’accueil, soit vous définissez une page qui affichera un contenu “statique”.

La solution réside donc dans l’intégration d’une WP Query au sein de votre modèle de page.

Mais en utilisant le bloc “Derniers articles” de Gutenberg, je pourrais le faire non ?

C’est vrai, mais ce bloc est très limité en terme de données affichées, et de style ! Du coup, on va privilégier l’approche à la main !

Au delà des articles, la WP Query marche pour tous les types de publication. Vous pourriez alors vous en servir pour différents cas de figure : comme par exemple afficher les dernières recettes sur un site de cuisine, ou encore les formations disponibles sur un site e-learning (et c’est d’ailleurs ce que j’ai fait sur ce site)…

Au fur et à mesure, vous vous rendrez compte qu’il existe de nombreux cas dans lesquels elle vous sera utile. À tel point que j’en ai eu l’utilité sur tous mes projets, sans exception !

Conseil

Il faut voir WordPress comme un framework qui vous fournit tous les outils nécessaires pour vous aider à créer votre thème. Du coup, il est très peu probable que vous ayez besoin de manipuler directement la base via SQL.

Dans la suite de ce cours on va par utiliser la WP Query pour faire nos requêtes sur mesure, et on verra dans le prochain cours comment modifier celle qui a permis de générer la page affichée.

Quelle différence avec le champ relationnel d’ACF ?

Précédemment, on a vu comment tirer parti d’ACF ainsi que l’utilisation du champ relationnel. Ce dernier permet au rédacteur de choisir à la main quelles publications afficher, et dans quel ordre.

Le champ relationnel d'ACF
Le champ relationnel d’ACF

Même si c’est très pratique, parfois il n’y a pas besoin d’autant de contrôle. Si vous voulez simplement afficher les 3 derniers articles en date, et ce automatiquement, alors la WP Query est toute indiquée.

Créer sa propre requête grâce à la WP Query

On va maintenant créer notre propre requête, et pour cela on va procéder en 4 étapes. Voici le code PHP correspondant, qu’il faudra placer dans le modèle de votre page (par exemple front-page.php), à l’endroit où vous souhaiter afficher le contenu.

Pour savoir quel modèle utiliser, il faudra se référer au Template Hierarchy, que l’on a vu plus tôt dans cette formation.

PHP
page.php

1 • Les paramètres (query vars)

Les paramètres sont les critères qui vont nous permettre de filtrer les résultats que l’on souhaite obtenir. Ils sont passés sous forme de tableau PHP (array) à notre requête. Il en existe plus d’une cinquantaine différents et on les appelle les query vars.

Vous allez donc pouvoir trier vos résultats par type de publication, date, auteur, catégorie, mais aussi choisir l’ordre d’affichage…

Pour s’y retrouver, il faut impérativement consulter la documentation officielle de la WP Query :

C’est le genre de ressources qui, comme le template hierarchy, aurait tout intérêt à finir dans les favoris de votre navigateur.

Dans l’exemple ci-dessus, j’ai indiqué 3 paramètres ou query vars :

  • Le type de publication doit être un article (post). J’aurais pu choisir une page, ou tout autre type de publication (custom post type) que vous auriez créé.
  • La catégorie doit être un film. category_name permet de chercher via le slug de la catégorie, mais j’aurais pu tout autant indiquer l’ID en utilisant cat.
  • Et enfin le nombre d’articles à récupérer est défini par posts_per_page, et je l’ai défini à 3.

Plus vous utiliserez de paramètres et plus vous allez pouvoir préciser votre besoin.

2 • La requête

Une fois les paramètres définis, on lance la classe PHP WP_Query() via le mot clé new. Et on passe nos paramètres en argument. WordPress s’occupe du reste : il va notamment générer lui-même la requête SQL. Notre classe est stockée dans la variable que j’ai appelée $my_query.

3 • La boucle

Ensuite, on va lancer une boucle WordPress, de la même manière qu’on lance la boucle principale dans nos templates. Il y a une petite différence tout de même puisque on ajoute le préfixe $my_query.

PHP

Dans cette boucle, on a utilise les mêmes templates tags que dans la boucle principale, tels que the_title(), the_content()… Notre requête personnalisée a donc en quelques sorte écrasé la requête principale !

4 • La réinitialisation

Du coup comment faire pour y revenir lorsqu’on en a fini avec notre WP Query personnalisée ? Eh bien on va utiliser la fonction wp_reset_postdata().

Qu’est-ce qu’il se passe concrètement dans WordPress à ce moment là ?

Au début de notre boucle, the_post() initialise les fonctions comme the_title() et the_content(), qui afficheront les données de notre requête.

Mais une fois qu’on en a terminé, il faut revenir à la boucle principale afin d’accéder à nouveau aux données originales de la page. Heureusement, WordPress a gardé ces informations de côté et on les retrouve grâce à wp_reset_postdata().

PHP
page.php

Je ne vous cache pas que c’est un peu de gymnastique, puisqu’on imbrique notre boucle dans la boucle principale. C’est la manière dont est conçu WordPress qui apporte cette complexité inutile mais on verra plus tard qu’en utilisant Timber, on n’aura plus ce souci.

À éviter

N’oubliez donc jamais de terminer vos requêtes personnalisées par wp_reset_postdata afin de retourner dans la boucle principale.

Les paramètres les plus courants de la WP Query

On va maintenant voir les paramètres les plus courants de la WP Query, ceux dont vous serez le plus susceptible d’utiliser au quotidien. Je ne vais pas tous vous les montrer, car il en existe un sacré nombre ! D’ailleurs il suffit de voir la hauteur de la page de la documentation officielle pour s’en rendre compte.

Filtrer par type de publication

En général lorsqu’on veut récupérer des données, c’est dans un type de publication en particulier : on va alors vouloir récupérer en particulier des articles, une page, ou bien tout autre custom post type créé par vos soins comme on a pu l’apprendre précédemment.

PHP
page.php

Faire une recherche

Vous pouvez également lancer une recherche avec un mot-clé. Pour cela il faut utiliser le paramètre s. WordPress s’occupera ensuite de chercher une occurence dans le contenu ou le titre de la publication. Vous pourriez également limiter la recherche à un type de publication en particulier, et non pas sur tout le site.

PHP
page.php

Ordre d’affichage

En plus du filtre, on aura souvent besoin de ranger les résultats dans un certain ordre, et pour cela on a deux paramètres à notre disposition :

  • order permet de choisir si on veut un rangement ascendant ou descendant (123 ou 321) ;
  • orderby permet de choisir sur quelle donnée faire ce tri : le titre, la date, le nombre de commentaires, ou même sur la valeur d’un champ personnalisé (champ ACF compris).
PHP
page.php

Dans cet exemple je récupère les articles, par ordre chronologique du plus récent au plus ancien.

Rangement basé sur un champ ACF

Imaginons maintenant que votre article possède un champ ACF Note, comme on l’a vu quand on a créé un système de notation de jeu vidéo via ACF. Votre objectif étant récupérer les 5 jeux les mieux notés. Voici à quoi ressemble notre array de paramètres :

PHP
page.php

Pas mal non ? Avec les bons paramètres, la WP Query nous permet d’aller très loin et récupérer tout ce dont on a besoin.

Limiter le nombre de résultats et pagination

Par défaut, la requête vous renvoie le nombre d’articles définis dans Réglages > Lecture, donc 10 si vous n’avez pas touché à ce paramètre. Si je les avais tous voulus, j’aurais indiqué -1.

PHP
page.php

Il existe également le paramètre offset qui permet de gérer une pagination. Il permet de dire par exemple : je veux 10 articles mais en commençant à la page 3 . On obtiendra alors les articles 21 à 30.

PHP
page.php

Grâce à cela vous pouvez créer facilement une pagination. Il suffirait d’un bouton page suivante avec une valeur qui s’incrémente de 10 en 10, et passée en paramètre GET.

PHP

Requêtes sur les dates

On peut également faire des requêtes très poussées sur les dates. On peut par exemple récupérer un article publié dans un intervalle précis, ou publié avant ou après telle date.

PHP
page.php

Il y a plusieurs façons d’écrire les dates : vous pourriez l’écrire à l’américaine (comme dans le after), ou en distinguant l’année, le mois et le jour (comme dans le before). Vous pourriez même utiliser des dates relatives comme 1 year ago (il y a un an). Référez-vous à la section dates de la documentation pour plus d’exemples.

Requêtes sur les champs personnalisés (dont ACF)

On a vu comment ranger nos résultats via une valeur contenue dans un champ ACF, mais on va pouvoir aller encore plus loin, et carrément filtrer les articles en fonction de valeurs contenues dans nos champs.

PHP
page.php

Dans cet exemple je souhaite récupérer seulement les jeux vidéos dont le prix est inférieur à 20€.

Et on va même aller encore plus loin grâce à la possibilité d’en cumuler plusieurs ! Mais dans ce cas l’écriture sera un peu plus complexe : on va utiliser une meta_query :

PHP
page.php

Alors qu’est-ce qu’on récupère ici selon vous ? On a demandé des jeux vidéo dont le prix serait situé entre 20 et 49€, ET dont la note serait supérieure à 16/20.

En changeant la relation pour OR, on aurait plutôt récupéré les jeux répondant au minima à l’une des 2 conditions.

Bien sûr, si vous testez une requête aussi restrictive, pensez à vérifier que vous avez bien des articles qui correspondent à tous ces critères en même temps, au risque sinon de ne rien voir s’afficher.

Dans ce cas on commence à aller dans des logiques de tableaux et sous-tableaux, et du coup attention à ne pas se tromper dans l’écriture de votre requête !

Conseil

La WP Query permet de faire des requêtes sur les champs ACF sans souci de compatibilité, ce qui vous ouvre tout un champ des possibles.

Comment connaitre le nombre d’articles retournés par la WP Query ?

Une fois votre WP Query effectuée, vous aurez peut-être des fois besoin d’afficher le nombre de résultats trouvés. On peut pour cela utiliser la méthode found_posts.

PHP
page.php

La WP Query est un élément essentiel du coeur de WordPress, et un outil très utile pour le développeur de thèmes. Dans la pratique, on l’utilise très régulièrement même si parfois on préférera utiliser le champ relationnel d’ACF.

Dans le prochain cours, on va voir cette fois comment modifier la WP Query utilisée par WordPress pour générer une page, dans le cas où l’on aurait besoin de rajouter des filtres avant le chargement de la page.

20

Questions, réponses et commentaires

  1. Mary

    Le 8 mai 2021

    Bonjour, J’ai une question qui est probablement bête, mais bon, j’ai besoin de la réponse pour être sûre de bien comprendre. Donc en fait la page “page.php” est à la base une page d’accueil statique, c’est à dire qu’on ne peut pas faire appel à la bdd pour récupérer des infos, mais grâce à la wp_query, cela rend en quelque sorte notre page dynamique ? Est ce que j’ai bien compris ? Merci beaucoup pour votre réponse. Cordialement

    1. Maxime BJ

      Le 10 mai 2021

      La WP Query est utilisée à la base par WordPress pour récupérer les informations de la base de données en fonction de la page demandée (une certaine page, le blog, un article). Mais on peut également l’utiliser dans une page pour aller chercher des informations supplémentaires lorsqu’on en a besoin. Cela nous permettrait par exemple, pour une page d’accueil, d’aller chercher la liste des 3 derniers articles du blog en plus des informations de la page. On peut donc ensuite construire des pages plus complètes.

  2. Victoria

    Le 24 mai 2022

    Bonjour, j’ai une question.

    Je suis un peu perdue par rapport des pages. Je travaille actuellement sur un projet d’un site de landing page pour présenter une petite entreprise. Etant débutante, j’apprends vos cours du tutoriel afin que je puisse me progresser :).

    Je souhaite faire une seule page de landing pages qui consiste :
    – une section (page d’accueil avec le carrousel)
    – une section (présentation des missions)
    – une section (liste des articles)
    – une section (Liste des evenements)
    – une section (présentation de l’équipe).

    J’ai reussi à faire les sections avec les contenus dans la page “front-page.php” en utilisant le CPT et WP Query. Sauf que j’ai une seule problème pour celle de la section (avec la liste des articles), j’ai reussi d’afficher les articles, mais cela ne fonctionne pas pour la padgnitation… Et le menu (j’ai desactivé le menu défaut de wordpress car les pages par défaut de WordPress se séparent, ce n’est pas ce que je voulais) du coup j’ai fait manuellement avec le systeme classique d’ID (html) mais je ne sais pas si c’est une bonne solution ce que j’ai fait.) Que pouvez vous me donner les conseils ? Merci beaucoup 🙂

    1. Maxime BJ

      Le 24 mai 2022

      Salut Victoria, je pense que tu es sur la bonne voie !
      La WP Query est définitivement la bonne approche. Pour les autres sections, tu pourrais utiliser des champs ACF pour rendre les contenus administrables, et ça tombe bien car on l’aborde plus tard dans la formation.
      Tu peux faire un menu, affiché seulement sur cette page, dans lequel tu mets des éléments personnalisés, où tu choisis l’URL afin de mettre tes ancres (#section). De cette manière, tu conserves la possibilité d’administrer le menu.
      Concernant la pagination, elle devrait marcher normalement, tant que tu la places avant wp_reset_postdata();

  3. Maxime

    Le 10 juin 2022

    Bonjour, Est-ce-que Grace à wp query je pourrai par exemple faire une requête d’une page qui diffuse des actualité pour ensuite l’afficher sur ma page WP ? car j’ai un site web et je voudrais qu’a la fin de mon site s’affiche les articles d’une autre page web Merci en tout cas tes tuto sont d’une grande qualité : )

    1. Maxime BJ

      Le 10 juin 2022

      Oui c’est tout à fait son rôle ! Tu peux du coup afficher des requêtes qui récupèrent n’importe quel type de contenu de ton site, sur n’importe quelle page.

  4. Hermann Aledohan

    Le 4 septembre 2022

    Bonjour a tous,
    Je veux afficher sur chaque publication personnalisée les valeurs de ses champs personnalisés. Par exemple, 2 articles d’une publication personnalisée musique avec 3 champs personnalisés attribut, avis, qualité et je veux afficher chaque article musique avec son attribut unique, avis unique et qualité unique. Est-ce que wp_query peut être utilisé dans ce cas. Si oui, comment faire cette requête ?

    1. Maxime BJ

      Le 4 septembre 2022

      Tu vas avoir besoin d’ACF pours les attributs supplémentaires, qu’on va justement aborder plus tard dans la formation. Ensuite ça va dépendre de comment tu veux gérer ça :
      – si tu veux que les articles s’affichent automatiquement (via des critères précis) alors tu pourras utiliser la WP Query. Mais si tu préfères pouvoir choisir tes musiques pour chaque article, alors ACF te proposera un champ pour sélectionner facilement les articles à afficher. Au final ce dernier utilisera une WP Query aussi, mais le code sera légèrement différent. Je t’invite à continuer la formation, je pense que tout sera clair à l’issue de la partie ACF.

  5. Abel Giraud

    Le 21 février 2023

    Bonjour,

    Je suis actuellement entrain de créer un site avec WP pour une association qui s’occupe de chat errant et leur trouve des propriétaire.
    Je n’ai pas du tout l’habitude de wordpress qui est très pratique pour le front-end mais avec lequel j’ai du mal avec le back-end.
    Dans le site j’ai donc une page adoption dans la quelle j’affiche les chats sous forme de card (photo, nom, description).
    M’étant perdu dans les tuto je ne comprend pas comment prendre les données de chaque chats dans la base de données pour les afficher donc sous forme de card et que ces card puisse être créer, modifier et supprimer depuis le site (la base de données pour les chats devrait être remplis depuis le site facilement les personnes de l’asso ni connaissent rien en info, bdd etc)
    Je ne sais pas si je suis très claire mais j’ai énormément besoin d’aide car je commence à prendre du retard.
    Merci pour l’attention que vous porterez à ma requête.

    1. Maxime BJ

      Le 21 février 2023

      Il faut que tu créées un type de publication personnalisé “Chats” (CPT = custom post type), qui se comportera comme les articles. Les chats auront donc une page archive : archive-chats.php et un page single : single-chats.php. L’archivera affichera la liste des chats, et la single sera la page dédié à l’un d’entre-eux. Le cours correspondant est ici : https://capitainewp.io/formations/developper-theme-wordpress/types-publication-taxonomies/ Je te conseille de consulter les 4 cours de la partie 2C. Ils t’apporteront toutes tes réponses.
      Du coup, pas besoin de WP Query personnalisée, puisque ce sera WordPress qui gérera la requête pour toi.

      1. Abel Giraud

        Le 21 février 2023

        Très bien merci beaucoup je vais suivre le cours que vous m’avez renseigné.
        puis-je revenir vers vous si je rencontre des problèmes ?

        1. Maxime BJ

          Le 22 février 2023

          Je pourrais répondre aux questions généralistes qui concernent directement le cours, mais je ne fais pas d’accompagnement personnalisé par contre.

  6. Aozoke

    Le 7 mars 2023

    Bonjour,

    Je recherche afficher sur ma page d’accueil seulement les 4 dernières images publier sur la galerie de mon acf. Est-ce possible ?
    J’ai une boucle personnalisé qui vas bien récupérer ma galerie, mais qui l’affiche au complet, hors je ne voudrais que les 4 dernières image de cette galerie : 9, )); ?>

    Merci

    1. Maxime BJ

      Le 7 mars 2023

      Du coup ça ne sera pas une WP Query puisque tu vas chercher les méta de ton post (la WP Query va chercher les posts justement). Il te suffirait, dans ta boucle d’affichage des images de ta galerie, de rajouter un compteur que tu incrémentes à chaque itération de la boucle et de n’afficher l’image que si ce compteur est inférieur à 4.

  7. Le Bail Etienne

    Le 25 avril 2023

    Bonjour,
    J’utilise le plugin Query et j’ai ajouter le code PHP grâce à l’extension Snippets afin que les évènements de ma page “Agenda” soient filtré en fonction de la date de sorti la plus récente. Cependant il n’y a aucun changement et je ne comprends pas pourquoi ? Pourriez vous m’aidez ?

    1. Maxime BJ

      Le 25 avril 2023

      Bonjour Étienne, hélas je ne pourrais pas t’aider sur un besoin aussi spécifique. La WP Query va générer une liste de publications au chargement de la page. Si tu veux ensuite manipuler cette liste en JS, il faudra une requête Ajax pour aller chercher, côté serveur, une nouvelle WP Query.

  8. adam Refined

    Le 17 juin 2023

    Salut, dans la partie 4 (concepts avancés), il y a beaucoup de “leçons” qui sont en cours de préparation. Est-ce que c’est possible d’avoir une date même approximative par rapport à la mise en ligne des cours ? Merci 🙂

    1. Maxime BJ

      Le 19 juin 2023

      Hélas je ne sais pas quand j’aurais le temps d’avancer cette partie ! J’y réfléchis de plus en plus cela dit.

  9. lilou

    Le 21 novembre 2023

    Bonjour,

    J’ai un problème avec la WP_Query. J’ai une page qui affiche des petites annonces sous forme de carte (une image, un titre, un texte et un lien pour voir le détail de l’annonce) dans un layout en grille. J’utilise un CPT pour les petites annonces. Quand j’utilise la Loop WordPress classique dans la page archive il n’y a pas de problème, j’ai la pagination qui marche et le bon nombre de petites annonces qui s’affiche par page. Mais dès que j’utilise la WP_Query pour ordonner mes petites annonces par une meta_key, la pagination ne marche pas, il n’y a pas toute les petites annonces et c’est toujours les mêmes petites annonces qui s’affichent.
    Est-ce que vous pouvez me dire comment résoudre ce problème ?

    1. Maxime BJ

      Le 22 novembre 2023

      la WP query permet de créer une requête supplémentaire dans ta page, en plus de la requête principale. Toi ce que tu veux, c’est modifier la requête de WordPress qui existe déjà dans le modèle de page. Dans ce cas il faut que tu modifies ses paramètres en amont. Il faut que tu utilises le hook pre_get_posts(). J’explique justement tout cela dans le cours suivant : https://capitainewp.io/formations/developper-theme-wordpress/modifier-parametres-boucle-wordpress/

Laisser un commentaire