Aller au contenu principal
Version: Next

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​

info

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.

app/Controllers/HomeController.php
$estateQuery = $this->getPostType("estate")->getQuery(); // Option 1
$queryResult = Query::all('estate'); // Option 2
info

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.

attention

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 : -1 pour 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).

attention

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 :

ChampAliasDescription
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 :

  • > ou after : Après une date (non inclusif)
  • >= ou after_inclusive : Après ou égal à une date
  • < ou before : Avant une date (non inclusif)
  • <= ou before_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.

Version

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 :

app/Controllers/ArchiveController.php
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 (ASC ou DESC, 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'instance WP_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

app/Controllers/ArchiveController.php
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​

  1. Réinitialisation automatique : Après chaque exécution, la façade Query réinitialise automatiquement ses arguments internes.

  2. Collection d'objets Post : Depuis la version 26.0.10.0, les résultats sont retournés dans une Collection d'objets Post. 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;
    }
  3. Champs personnalisés : Les champs inclus via include() sont automatiquement chargés dans la propriété fields de chaque objet Post.

  4. Termes de taxonomie : Les termes récupérés via withTaxonomy() sont automatiquement chargés dans la propriété taxonomies de chaque objet Post.

  5. WP_Query native : Pour obtenir une instance WP_Query au lieu d'une Collection, passez false comme deuxième paramètre à get() ou utilisez getQuery().

  6. Pagination : Utilisez paginate() et getPaged() pour gérer la pagination. La fonction Twig paginate() peut être utilisée pour afficher les liens de pagination.