Query
Query est une façade à WP_Query permettant de faciliter l'écriture des requêtes.
On peut considérer que c'est un mini ORM pour WordPress et ses post types.
Créer une requête
Ici, le code présenté sera exécuté dans une méthode de controller utilisant l'attribut Template pour rendre une vue Twig.
Tout d'abord, on commence avec une requête simple, on récupère tous les posts du type estate.
Dans ce cas, on peut se passer de la façade Query et utiliser directement la méthode getQuery du post type.
$estateQuery = $this->getPostType("estate")->getQuery(); // Option 1 $queryResult = Query::all('estate'); // Option 2
Depuis la version 26.0.10.0, la façade Query retourne une Collection d'objets Post au lieu d'un tableau brut de WP_Post. Cela permet d'utiliser directement les méthodes de la façade Post sur chaque résultat.
Pour que Query retourne une instance WP_Query au lieu d'une Collection, passez false comme deuxième paramètre à get().
Méthodes disponibles
all($post_type, $posts_per_page)
Récupère tous les posts d'un type donné.
Paramètres :
$post_type(string) : Le type de post à récupérer (défaut :'post')$posts_per_page(int) : Nombre de posts par page (défaut :-1pour tous)
Retourne : Collection<Post>|WP_Query - Une Collection d'objets Post ou une instance WP_Query
Exemple :
// Récupère tous les posts de type 'estate' $estates = Query::all('estate'); // Chaque élément est un objet Post avec ses méthodes foreach ($estates as $estate) { echo $estate->title; echo $estate->get_field('price'); } // Récupère les 10 premiers posts de type 'article' $articles = Query::all('article', 10);
find($id, $post_type)
Récupère un post spécifique par son ID.
Paramètres :
$id(int) : L'ID du post à récupérer$post_type(string) : Le type de post (défaut :'post')
Retourne : Post - Un objet Post
Exemple :
// Récupère le post avec l'ID 80 $post = Query::find(80, 'estate'); // Accès direct aux propriétés et méthodes de Post echo $post->title; echo $post->get_field('price'); echo $post->taxonomy('category')?->menuName;
where($field, $operator, $value)
Ajoute une condition à la requête. Cette méthode gère les champs natifs de WordPress et les meta-données (champs personnalisés).
La méthode where() ne gère pas les taxonomies. Pour filtrer par taxonomie, utilisez withTaxonomy().
Paramètres :
$field(string) : Le champ sur lequel appliquer la condition$operator(string) : L'opérateur de comparaison (=,like,>,<,>=,<=,after,before, etc.)$value(mixed) : La valeur à comparer
Retourne : self - Permet l'enchaînement
Champs natifs supportés :
| Champ | Alias | Description |
|---|---|---|
ID, id | - | ID du post |
post_title, title | - | Titre du post |
post_name, slug | - | Slug du post |
post_type, type | - | Type de post |
post_status, status | - | Statut du post |
post_author, author | - | Auteur du post |
post_date, date | - | Date de publication |
Opérateurs pour les dates :
>ouafter: Après une date (non inclusif)>=ouafter_inclusive: Après ou égal à une date<oubefore: Avant une date (non inclusif)<=oubefore_inclusive: Avant ou égal à une date=: Égal à une date spécifique
Exemple :
// Recherche par titre exact Query::where('post_title', '=', 'laversines')->get('estate'); // Recherche partielle dans le titre Query::where('post_title', 'like', 'versin')->get('estate'); // Filtre par statut Query::where('post_status', '=', 'publish')->get('estate'); // Filtre par auteur Query::where('post_author', '=', 5)->get('estate'); // Filtre par date (après le 1er janvier 2024) Query::where('post_date', '>', '2024-01-01')->get('estate');
limit($limit)
Limite le nombre de résultats retournés.
Paramètres :
$limit(int) : Le nombre maximum de posts à retourner
Retourne : self - Permet l'enchaînement
Exemple :
// Récupère uniquement les 4 premiers posts Query::limit(4)->get('estate');
paginate($postsPerPage, $paged)
Configure la pagination des résultats.
Paramètres :
$postsPerPage(int) : Nombre de posts par page (défaut :10)$paged(int) : Numéro de page actuel (défaut :1)
Retourne : self - Permet l'enchaînement
Exemple :
// Pagination avec 10 posts par page $paged = Query::getPaged(); $posts = Query::paginate(10, $paged)->get('estate'); // OU $posts = Query::paginate(10)->get('estate') // $paged est défini automatiquement. // Dans Twig {% for post in posts %} <h2>{{ post.title }}</h2> {% endfor %} {# Pagination avec la fonction paginate() #} {{ paginate(posts) }}
getPaged($paged)
Récupère le numéro de page actuel en tenant compte des variables de requête WordPress.
Disponible depuis la version 26.0.10.0.
Paramètres :
$paged(int) : Valeur par défaut (défaut :1)
Retourne : int - Le numéro de page actuel
Exemple :
// Récupère la page actuelle depuis l'URL $paged = Query::getPaged(); // Utilisation avec paginate() $posts = Query::paginate(10, $paged)->get('estate');
Utilisation dans un controller :
use Elementum\Facades\Query; use Elementum\Attributes\Template; class ArchiveController { #[Template('post_type_archive', params: ['estate'])] public function index(): array { $postsQuery = Query::orderBy('date', 'DESC') ->paginate(10) ->get('estate', return_posts: false); return $this->render('@theme/estate-archive.html.twig', compact('postsQuery')); } }
paginate($postsPerPage, $paged)
Configure la pagination des résultats.
Paramètres :
$postsPerPage(int) : Nombre de posts par page (défaut :10)$paged(int) : Numéro de page actuel (défaut :1)
Retourne : self - Permet l'enchaînement
Exemple :
// Pagination avec 10 posts par page Query::paginate(10)->get('estate'); // Pagination avec page spécifique Query::paginate(10, 2)->get('estate'); // Page 2
getPaged($paged)
Récupère le numéro de page actuel en tenant compte des variables de requête WordPress.
Paramètres :
$paged(int) : Valeur par défaut (défaut :1)
Retourne : int - Le numéro de page actuel
Exemple :
$paged = Query::getPaged(); Query::paginate(10, $paged)->get('estate');
withTaxonomy($taxonomy, $get_terms)
Inclut des taxonomies dans la requête et récupère les termes associés.
Paramètres :
$taxonomy(string|array) : La ou les taxonomies à inclure$get_terms(bool) : Si true, récupère les termes associés à chaque post (défaut :true)
Retourne : self - Permet l'enchaînement
Exemple :
// Inclut une seule taxonomie Query::withTaxonomy('caracteristics')->get('estate'); // Inclut plusieurs taxonomies Query::withTaxonomy(['type', 'caracteristics'])->get('estate'); // Inclut sans récupérer les termes Query::withTaxonomy('type', false)->get('estate');
include($fields)
Inclut des champs personnalisés (meta-données) dans les résultats.
Paramètres :
$fields(string|array) : Le ou les champs à inclure
Retourne : self - Permet l'enchaînement
Exemple :
// Inclut un seul champ Query::include('estate_price')->get('estate'); // Inclut plusieurs champs Query::include(['estate_price', 'estate_surface'])->get('estate');
orderBy($field, $direction)
Définit l'ordre des résultats.
Paramètres :
$field(string) : Le champ sur lequel trier$direction(string) : La direction du tri (ASCouDESC, défaut :ASC)
Retourne : self - Permet l'enchaînement
Exemple :
// Tri par titre croissant Query::orderBy('post_title', 'ASC')->get('estate'); // Tri par date décroissante Query::orderBy('date', 'DESC')->get('estate'); // Tri par meta-donnée Query::orderBy('meta_value_num', 'ASC')->get('estate');
get($post_type, $return_posts)
Exécute la requête et retourne les résultats.
Paramètres :
$post_type(string) : Le type de post à récupérer (défaut :'post')$return_posts(bool) : Si true, retourne les posts, sinon retourne l'instance WP_Query (défaut :true)
Retourne : array|WP_Query - Un tableau d'objets WP_Post ou une instance WP_Query
Exemple :
// Exécute la requête et retourne les posts $posts = Query::orderBy('title', 'ASC')->get('estate'); // Exécute la requête et retourne l'instance WP_Query $query = Query::orderBy('title', 'ASC')->get('estate', false);
getQuery($post_type)
Retourne l'instance WP_Query pour une utilisation dans une boucle WordPress classique.
Paramètres :
$post_type(string) : Le type de post à récupérer (défaut :'post')
Retourne : WP_Query - Une instance de WP_Query
Exemple :
// Récupère l'instance WP_Query $query = Query::getQuery('estate'); // Utilisation dans une boucle WordPress if ($query->have_posts()) { while ($query->have_posts()) { $query->the_post(); the_title(); } wp_reset_postdata(); }
convert($query)
Convertit une instance WP_Query existante pour utiliser la façade Query.
Paramètres :
$query(WP_Query) : L'instanceWP_Queryà convertir
Retourne : self - Une nouvelle instance de Query
Exemple :
// Convertit une WP_Query existante $existingQuery = new WP_Query(['post_type' => 'estate']); $query = Query::convert($existingQuery); // Peut ensuite être chaîné avec d'autres méthodes $results = Query::convert($existingQuery) ->include('estate_price') ->get('estate'); // Les résultats sont des objets Post foreach ($results as $post) { echo $post->title; echo $post->get_field('estate_price'); }
Cas d'usage : Hook WordPress
use Elementum\Facades\Query; // Dans un hook pre_get_posts add_action('pre_get_posts', function($mainQuery) { if (is_admin() || !$mainQuery->is_main_query()) { return; } if (is_post_type_archive('estate')) { $mainQuery->set('posts_per_page', 10); $mainQuery->set('orderby', 'date'); $mainQuery->set('order', 'DESC'); } }); // Dans le controller, conversion de la query principale #[Template('post_type_archive', params: ['estate'])] public function index(): array { global $wp_query; $posts = Query::convert($wp_query) ->include(['price', 'surface']) ->get('estate'); return $this->render('@theme/estate-archive.html.twig', ['posts' => $posts]); }
Exemples complets
Requête simple avec filtrage
// Récupère les estates avec un titre spécifique Query::where('post_title', '=', 'laversines')->get('estate');
Requête chaînée complexe
Query::where('post_title', 'like', 'versin') // Filtre par titre ->withTaxonomy('caracteristics') // Inclut la taxonomie ->include(['estate_price', 'estate_surface']) // Inclut les champs ->orderBy('date', 'ASC') // Trie par date ->limit(10) // Limite à 10 résultats ->get('estate'); // Exécute
Requête avec pagination
$paged = Query::getPaged(); Query::where('post_status', '=', 'publish') ->orderBy('date', 'DESC') ->paginate(10, $paged) ->get('estate');
Requête avec plusieurs conditions
Query::where('estate_price', '>', 300000) ->where('estate_surface', '>=', 100) ->withTaxonomy(['type', 'city']) ->orderBy('estate_price', 'ASC') ->get('estate');
Notes importantes
-
Réinitialisation automatique : Après chaque exécution, la façade Query réinitialise automatiquement ses arguments internes.
-
Collection d'objets Post : Depuis la version 26.0.10.0, les résultats sont retournés dans une
Collectiond'objetsPost. Chaque post dispose de toutes les méthodes de la façade Post :$posts = Query::all('estate'); foreach ($posts as $post) { echo $post->title; echo $post->get_field('price'); echo $post->taxonomy('category')?->name; } -
Champs personnalisés : Les champs inclus via
include()sont automatiquement chargés dans la propriétéfieldsde chaque objetPost. -
Termes de taxonomie : Les termes récupérés via
withTaxonomy()sont automatiquement chargés dans la propriététaxonomiesde chaque objetPost. -
WP_Query native : Pour obtenir une instance
WP_Queryau lieu d'une Collection, passezfalsecomme deuxième paramètre àget()ou utilisezgetQuery(). -
Pagination : Utilisez
paginate()etgetPaged()pour gérer la pagination. La fonction Twigpaginate()peut être utilisée pour afficher les liens de pagination.