WordPress get_posts est une fonction puissante permettant aux développeurs de récupérer des éléments de contenu depuis la base de données WordPress. Vous pouvez spécifier dans les moindres détails quels articles, pages et les types de publications personnalisés que vous recherchez, obtenir votre ensemble de résultats personnalisés, puis filtrer et trier les éléments comme un ninja PHP/MySQL.

Mais n’ayez pas peur si vous n’êtes pas un professionnel de PHP, il existe d’innombrables tutoriels PHP que vous pouvez regarder ou lire et apprendre ce langage.

Vous avez juste besoin d’un peu connaissance en PHP pour créer des listes personnalisées d’articles à afficher sur votre site car la fonction get_posts conserve un ensemble de paramètres permettant de construire des requêtes simples ou avancées.

Utiliser WordPress get_posts est un processus en deux étapes :

  • Tout d’abord, vous devez construire votre requête personnalisée. En fait, cela ne ressemblera pas à une requête MySQL, et vous n’écrirez aucune instruction SELECT. Il vous suffit de définir un tableau de paramètres et de le passer à la fonction get_posts. WordPress convertit ce tableau en une requête MySQL réelle et sécurisée, l’exécute contre la base de données et retourne un tableau d’articles.
  • Ensuite, vous devez parcourir l’ensemble des résultats retournés par get_posts avec un cycle foreach.

Cela dit, dans cet article, nous allons d’abord nous plonger dans les concepts clés mentionnés ci-dessus, en particulier comment get_posts fonctionne, comment construire une requête personnalisée, et comment afficher les données sur l’interface publique du site.
Ensuite, je vous fournirai un exemple réel avec un extrait de code que vous pourrez récupérer, modifier et utiliser sur votre environnement de test pour vos développements.

Note : Nous faisons généralement la différence entre les articles, les pages et les types de publications personnalisés. Dans cet article, nous utilisons le terme « posts » pour les articles de blog réguliers ainsi que pour les pages et les types de publications personnalisés. Tous ces types de publication sont stockés dans la table « wp_posts » de la base de données. La principale différence entre les types de publications réside dans la valeur du champ « post_type ». Du point de vue d’un développeur, les articles, les pages et les types de publications personnalisés sont tous des publications.

Introduction à la Fonction get_posts de WordPress

Le Codex décrit que la fonction get_posts comme ci-dessous :

Récupère un tableau des dernières publications, ou des publications correspondant aux critères donnés.

Nous pouvons utiliser get_posts de cette façon :

$args = array(
	'numberposts'	=> 20,
	'category'		=> 4
);
$my_posts = get_posts( $args );

if( ! empty( $my_posts ) ){
	$output = '<ul>';
	foreach ( $my_posts as $p ){
		$output .= '<li><a href="' . get_permalink( $p->ID ) . '">' 
		. $p->post_title . '</a></li>';
	}
	$output .= '<ul>';
}

 

La fonction ci-dessus récupère les 20 derniers articles de blog dans la catégorie spécifiée (par défaut le « post_type » est « post ») et retourne un tableau d’objets $post. Vous pouvez itérer sur le tableau pour afficher les articles à l’écran. C’est assez facile, non ?

get_posts utilise WP_Query pour récupérer les éléments de publications, et il conserve un tableau des mêmes paramètres disponibles dans WP_Query (à quelques exceptions près). Nous avons donc une énorme liste de variables que nous pouvons utiliser pour construire nos requêtes personnalisées. Ces paramètres sont regroupés en 15 catégories :

  • Paramètres d’auteur
  • Paramètres de catégorie
  • Paramètres d’étiquette
  • Paramètres de taxonomie
  • Paramètres de recherche
  • Paramètres d’article et de page
  • Paramètres de mot de passe
  • Paramètres de type de publication
  • Paramètres de tri et de tri par
  • Paramètres de date
  • Paramètres de champ personnalisé (post-méta)
  • Paramètres de permission
  • Paramètres de type mime
  • Paramètres de mise en cache
  • Paramètres de champs de retour

Un coup d’œil rapide à la liste ci-dessus peut vous donner une idée de la variété des requêtes personnalisées que vous pouvez construire et exécuter dans la base de données WordPress. Donc, plongeons plus profondément dans les paramètres de requête et commençons à construire nos listes de publications.

Comment Construire des Requêtes avec WordPress get_posts

Chaque catégorie de paramètres se rapporte à la même information. Par exemple, nous pouvons construire une requête pour récupérer les publications de l’auteur ou des auteurs spécifiés ou exclure l’auteur ou les auteurs spécifiés, en définissant l’auteur par ID ou pseudonyme. De la même manière, nous pouvons construire des requêtes en récupérant les publications par catégorie, étiquette, taxonomie, date, champs personnalisés et plus encore.

Comment Utiliser les Paramètres pour Construire des Requêtes Simples

De nombreux paramètres peuvent être utilisés de manière assez similaire, quelle que soit la catégorie à laquelle ils appartiennent. Par exemple, les paramètres suivants permettent d’interroger la base de données par auteur(s) de publication :

  • author (int) – ID auteur
  • author_name (string) – user_nicename de l’auteur
  • author__in (array) – un tableau d’ID d’auteurs multiples
  • author__not_in (array) – un tableau d’ID de plusieurs auteurs à exclure des résultats

Comment utiliser ces paramètres ?

Dans l’exemple suivant, le paramètre « author » spécifie que nous voulons les publications les plus récentes écrites par l’auteur avec ID = 1 :

$my_posts = get_posts( array( 'author' => 1 ) );

Le même paramètre « author » permet d’interroger la base de données de différentes manières :

// return an array of posts from specific authors
$my_posts = get_posts( array( 'author' => '1,5,12' ) );
// return an array of posts excluding the specified author
$my_posts = get_posts( array( 'author' => -1 ) );

Ainsi, en fonction de la valeur du paramètre, vous obtiendrez un ensemble de résultats avec les publications d’un seul auteur (entier), de plusieurs auteurs (liste des valeurs séparées par des virgules) ou excluant un auteur (valeurs négatives).

D’autres paramètres offrent une flexibilité supplémentaire. Par exemple, l’appel suivant pour get_posts retourne un tableau des dernières publications du blog de plusieurs auteurs :

// return an array of posts from multiple authors
$my_posts = get_posts( array( 'author__in' => array( 1, 5, 12 ) ) );

Et nous pouvons aussi exclure plusieurs auteurs :

// return an array of posts from multiple authors
$my_posts = get_posts( array( 'author__not_in' => array( 1, 5, 12 ) ) );

De même, nous pouvons utiliser les paramètres de catégorie, d’étiquettes, de type de publication, avec quelques différences spécifiques. Voir, à titre d’exemple, les paramètres de catégorie :

  • cat (int)
  • category_name (string)
  • category__and (array)
  • category__in (array)
  • category__not_in (array)

De toute façon, tous les paramètres ne sont pas aussi faciles à utiliser que ces paramètres. De plus, nous pouvons utiliser les paramètres de catégorie, les paramètres de type de publication, les paramètres de type mime, etc. en une seule requête. Cela signifie que nous avons un contrôle granulaire sur les éléments du jeu de résultats, et nous pouvons construire des requêtes plus avancées basées sur les types de publications, les taxonomies personnalisées et les champs personnalisés.

Alors, plongeons plus profondément !

Comment Construire des Requêtes Avancées dans WordPress

Faisons un pas en avant avec une requête plus avancée basée sur des types de publications et des taxonomies personnalisés. Supposons que vous ayez le type de publication suivant :

nom : book
nom de taxonomie : book_category, book_author
support pour: title, editor, thumbnail, excerpt, custom-fields

Types de Publications Personnalisés et Taxonomies Personnalisées

Supposons que vous vouliez une liste des livres les plus récents dans la taxonomie personnalisée book_category spécifiée. Voici le tableau des arguments :

$args = array(
	'post_type'		=> 'book',
	'tax_query'		=> array(
		array(
			'taxonomy'	=> 'book_category',
			'field'		=> 'slug',
			'terms'		=> 'sci-fi'
		)
	),
);

Les arguments ci-dessus disent simplement à WordPress de récupérer tous les livres dans « sci-fi » « book_category ».

Le paramètre « tax_query » prend un tableau de tableaux d’arguments (c’est-à-dire un tableau de tableaux). Ces tableaux imbriqués permettent de construire des requêtes très complexes basées sur des taxonomies multiples, comme le montre l’exemple ci-dessous :

$args = array(
	'numberposts'	=> 10,
	'post_type'		=> 'book',
	'relation'		=> 'AND',
	'tax_query'		=> array(
		array(
			'taxonomy'	=> 'book_category',
			'field'		=> 'slug',
			'terms'		=> 'sci-fi'
		),
		array(
			'taxonomy'	=> 'book_author',
			'field'		=> 'term_id',
			'terms'		=> 22
		)
	)
);

Ces paramètres nous permettent de récupérer une liste des 10 derniers types de publication « book » dans « sci-fi » « book_category », écrits par le « book_author » avec l’ID #22. Le paramètre « relation » définit la relation logique entre chaque taxonomie listée dans « tax_query ». Nous définissons sa valeur sur AND parce que nous avons besoin de récupérer tous les livres appartenant à la catégorie « sci-fi » AND écrits par l’auteur #22.

Comment Construire des Requêtes de Méta à l’aide de Paramètres de Champ Personnalisés

De temps en temps, vous pouvez avoir besoin de construire des listes de publications en fonction d’une clé et/ou d’une valeur de champ personnalisée spécifique.

$args = array(
	'meta_key'		=> 'cover',
	'meta_value'	=> 'paperback',
	'meta_compare'	=> '='
);

Ces paramètres nous permettent de récupérer toutes les publications par clé et valeur de champ personnalisée. « meta_compare » définit l’opérateur requis pour tester la valeur du paramètre « meta_value ». Ici, « meta_value » est « = », qui est aussi la valeur par défaut.

Les valeurs disponibles sont '=', '!=', '>', '>=', '<', '<=', 'LIKE', 'NOT LIKE', 'IN', 'NOT IN', 'BETWEEN', 'NOT BETWEEN', 'NOT EXISTS', 'REGEXP', 'NOT REGEXP' ou 'RLIKE'.

C’est un exemple assez simple, mais nous pouvons construire des requêtes plus avancées. Dans l’exemple suivant, nous interrogeons la base de données pour les livres fantastiques publiés après 2010 :

$args = array(
	'post_type'		=> 'book',
	'meta_key'		=> 'year_published',
	'meta_value_num'	=> 2010,
	'meta_compare'	=> '>',
	'tax_query'		=> array(
		array(
			'taxonomy'	=> 'book_category',
			'field'		=> 'slug'
			'terms'		=> 'fantasy'
		)
	)
);

Et nous pouvons aller encore plus loin. Dans l’exemple suivant, nous mélangeons un type de publication avec une taxonomie personnalisée et deux champs personnalisés :

$args = array(
	'post_type'		=> 'book',
	'tax_query'		=> array(
		array(
			'taxonomy'	=> 'book_category',
			'field'		=> 'slug'
			'terms'		=> array( 'fantasy' )
		)
	),
	'meta_query'	=> array(
		'relation'		=> 'AND',
		array(
			'key'		=> 'year_published',
			'value'		=> 2010,
			'type'		=> 'numeric',
			'compare'	=> '>',
		),
		array(
			'key'		=> 'price',
			'value'		=> array( 10, 25 ),
			'type'		=> 'numeric',
			'compare'	=> 'BETWEEN',
		)
	)
);

Ici, nous établissons un tableau de paramètres pour récupérer une liste de livres fantastiques publiés après 2010 qui coûtent BETWEEN 10 et 25$.

Vous pouvez voir que le paramètre « meta_query » fonctionne comme le paramètre « tax_query ». Il conserve un tableau de tableaux, ce qui nous permet d’effectuer des requêtes avancées basées sur de multiples paires méta-clés/valeurs. Pour une liste complète des paramètres de requête et un bon nombre d’exemples, voir la section WP_Query documentation.

Pourquoi get_posts est Limité à 5 Publications WordPress ?

La fonction get_posts prend les mêmes arguments que WP_Query::parse_query() (voir le Codex), mais certains paramètres spécifiques la rendent légèrement différente d’un objet WP_Query.

Peut-être que vous n’avez pas utilisé le paramètre « numberposts » dans vos requêtes et que vous vous demandez pourquoi vous ne voyez que 5 éléments dans votre liste.

Par défaut, le nombre de publications que vous définissez dans Paramètres → Lecture détermine le nombre de publications à récupérer dans une requête WordPress. Quoi qu’il en soit, si vous ne spécifiez pas de valeur personnalisée pour « numberposts » ou « posts_per_page », get_posts retourne un nombre différent de publications.

  • « number_posts » est le nombre total de publications à récupérer. C’est un alias de « posts_per_page » dans WP_Query, mais il y a une différence entre les deux : par défaut, le nombre de publications à récupérer en utilisant get_posts est 5, alors que « posts_per_page » dans WP_Query est le nombre de publications par page de votre blog WordPress. Vous pouvez remplacer la valeur par défaut en définissant une valeur personnalisée pour « numberposts » ou « posts_per_page » dans le tableau des arguments.

En plus de « numberposts », les paramètres suivants sont spécifiques à get_posts :

  • « category » est une liste d’ID de catégorie séparés par des virgules. C’est un alias du paramètre « cat » dans WP_Query.
  • « include » est une liste d’ID de publications séparés par des virgules. C’est un alias du paramètre « post__in » dans WP_Query.
  • « exclude » est une liste d’ID de mpublications séparés par des virgules.
  • « suppress_filters » spécifie s’il faut supprimer les filtres. Ce paramètre est sur true par défaut dans get_posts, alors qu’il est sur false par défaut dans WP_Query (voir la section sur Track).

La fonction get_posts est définie dans wp-includes/post.php. Vous pouvez vous plonger dans le fonctionnement de get_posts soit en vérifiant le code source sur Track (WordPress 5.2) ou dans votre installation WordPress locale.

Ordre des Publications

Les options « orderby » et « order » permettent de trier les éléments dans le jeu de résultats. Vous triez les publications par « ID », « author », « title », « name », « type », « date », « modified « , « parent », « rand », « comment_count » et de nombreuses autres façons, par ordre croissant ou décroissant.

Si vous avez une requête simple, il vous suffit de définir une valeur pour « order » et « orderby ». Dans l’exemple suivant, les publications sont triées par nom de publication par ordre croissant :

$args = array(
	'author'	=> '1,5,12',
	'orderby'	=> 'name',
	'order'		=> 'ASC'
);

C’est assez simple. Mais que se passerait-il si vous aviez une requête avancée ? Par exemple : Peut-on trier les éléments par une ou plusieurs valeurs de champ personnalisées dans une méta requête avancée ?

WordPress 4.0 et WordPress 4.2 ont apporté des améliorations importantes aux paramètres « orderby » et « meta_query ». Nous avons maintenant une nouvelle syntaxe pour classer par clauses spécifiques d’une méta requête. Grâce à la nouvelle syntaxe, nous pouvons utiliser des index pour créer des références aux clauses spécifiques de la méta requête à partir du paramètre « orderby ».

Grâce à ces améliorations, la méta requête dans l’exemple ci-dessus peut être écrite comme suit :

$args = array(
	'meta_query'	=> array(
		'relation'		=> 'AND',
		'year_clause' => array(
			'key'		=> 'year_published',
			'value'		=> 2010,
			'type'		=> 'numeric',
			'compare'	=> '>',
		),
		'price_clause' => array(
			'key'		=> 'price',
			'value'		=> array( 10, 25 ),
			'type'		=> 'numeric',
			'compare'	=> 'BETWEEN',
		)
	),
	'orderby' => 'price_clause',
);

Dans l’exemple ci-dessus, nous avons classé les éléments par « price_clause ».

Et nous pouvons faire encore plus. Depuis WordPress 4.0, nous pouvons passer par get_posts un tableau de méta-indexes de requête au lieu d’un index unique, comme dans l’exemple ci-dessous :

$args = array(
	'meta_query'	=> array(
		'relation'		=> 'AND',
		'year_clause' => array(
			'key'		=> 'year_published',
			'value'		=> 2010,
			'type'		=> 'numeric',
			'compare'	=> '>',
		),
		'price_clause' => array(
			'key'		=> 'price',
			'value'		=> array( 10, 25 ),
			'type'		=> 'numeric',
			'compare'	=> 'BETWEEN',
		)
	),
	'orderby' => array( 'price_clause' => 'ASC', 'year_clause' => 'DESC' ),
);

Félicitations, vous avez construit une méta requête avancée, et trié les résultats d’abord par « price_clause » en ordre croissant, puis par « year_clause » en ordre décroissant.

Voir la liste complète des options de tri dans le Codex.

Il est temps pour nous d’afficher les données.

Lectures suggérées : Comment créer et utiliser facilement une page phpinfo.

Comment Afficher les Données Retournées par get_posts

WordPress get_posts retourne un tableau d’objets WP_Post nous donnant accès à un certain nombre de variables pour chaque publication sélectionnée stockée dans la table de base de données wp_posts :

  • ID
  • post_author
  • post_name
  • post_type
  • post_title
  • post_date
  • post_date_gmt
  • post_content
  • post_excerpt
  • post_status
  • comment_status
  • ping_status
  • post_password
  • post_parent
  • post_modified
  • post_modified_gmt
  • comment_count
  • menu_order
Structure des tables wp_posts dans phpMyAdmin
Structure des tables wp_posts dans phpMyAdmin

Vous pouvez facilement accéder à ces données à l’aide d’un cycle foreach comme ci-dessous :

$custom_posts = get_posts( $args );

if( ! empty( $custom_posts ) ){
	$output = '<ul>';
	foreach ( $custom_posts as $p ){

		$output .= '<li><a href="' 
		. get_permalink( $p->ID ) . '">' 
		. $p->post_title . '</a></li>';
	}

	$output .= '</ul>';
}

return $output ?? '<strong>Sorry. No posts matching your criteria!</strong>';

Si get_posts a trouvé au moins une publication, il retourne un tableau d’éléments que nous pouvons parcourir pour afficher le titre et un lien vers la publication originale. Nous avons utilisé la fonction get_permalink pour récupérer le lien permanent de la publication, car nous n’avons pas de variable WP_Post correspondante.

C’est assez facile, mais comment pouvons-nous implémenter ce code et construire nos listes de publications personnalisées en utilisant les get_posts de WordPress ?

Vous pouvez afficher les listes de publications sur vos pages de plusieurs façons.

Exemple du Monde Réel : Comment Afficher une Liste Personnalisée d’Éléments avec un Code Court

Je vais vous montrer comment construire un code court rapide et facile que vous pouvez inclure dans votre contenu. Quoi qu’il en soit, je ne vais pas m’enfoncer dans les codes courts, car nous avons déjà abordé ce sujet dans un précédent article de blog.

Tout d’abord, créez un nouveau répertoire dans le dossier wp-content/plugins de votre répertoire WordPress local ou dans un fichier environnement de test. Dans cet exemple, j’ai nommé le répertoire kinsta-shortcodes.

Dans wp-content/plugins/kinsta-shortcodes/crie un fichier.php du même nom que le nouveau répertoire : kinsta-shortcodes.php.

Ouvrez le nouveau fichier dans votre dossier éditeur de texte favori et incluez l’en-tête suivant :

<?php
/**
 * @package Kinsta_shortcodes
 * @version 1.0
 */
/*
Plugin Name: Kinsta shortcodes
Plugin URI: http://wordpress.org/extend/plugins/#
Description: This is an example plugin 
Author: Your Name
Version: 1.0
Author URI: https://yourwebsite.com/
*/

Maintenant nous avons une toute nouvelle extension, mais elle ne fait toujours rien. Naviguez jusqu’à l’écran d’administration des extensions dans votre tableau de bord WordPress et activez la nouvelle extension en vous assurant que WP_DEBUG est à true dans votre fichier wp-config.php.

Votre sandbox est maintenant prête pour vos hacks. L’étape suivante consiste à enregistrer un hook pour un code court personnalisé :

/**
 * Add a hook for a shortcode tag
 */
function kinsta_shortcodes_init(){
	add_shortcode( 'kinsta_get_posts', 'kinsta_get_posts_cb' );
}
add_action('init', 'kinsta_shortcodes_init');

kinsta_get_get_posts est le nom du code court et kinsta_get_posts_cb est le callback défini ci-dessous :

/**
 * Register a shortcode
 *
 * @param array $atts Array of shortcode attributes
 */
function kinsta_get_posts_cb( $atts ){

	// safely extract custom arguments and set default values
	extract( shortcode_atts(
			array(
				'numberposts'		=> 3,
				'post_type'			=> 'post',
				'book_category'		=> 'fantasy',
				'year_published'	=> 1900,
				'price_min'			=> 0,
				'price_max'			=> 50
			),
			$atts,
			'kinsta_get_posts'
		) );

	// define the array of query arguments
	$args = array(
		'numberposts'	=> $numberposts,
		'post_type'		=> $post_type,
		'tax_query'		=> array(
			array(
				'taxonomy'	=> 'book_category',
				'field'		=> 'slug',
				'terms'		=> $book_category,
			)
		),
		'meta_query'	=> array(
			'relation'		=> 'AND',
			'year_clause'	=> array(
				'key'		=> 'year_published',
				'value'		=> $year_published,
				'type'		=> 'numeric',
				'compare'	=> '>',
			),
			'price_clause'	=> array(
				'key'		=> 'price',
				'value'		=> array( $price_min, $price_max ),
				'type'		=> 'numeric',
				'compare'	=> 'BETWEEN',
			)
		),
		'orderby' => array( 'price_clause' => 'ASC' )
	);

	$custom_posts = get_posts( $args );

	if( ! empty( $custom_posts ) ){
		$output = '<ul>';
		foreach ( $custom_posts as $p ){

			$output .= '<li><a href="' 
			. get_permalink( $p->ID ) . '">' 
			. $p->post_title . '</a> (' 
			. get_post_meta( $p->ID, 'year_published', true ) 
			. ') - Price: ' . get_post_meta( $p->ID, 'price', true ) . '</li>';
		}

		$output .= '</ul>';
	}

return $output ?? '<strong>Sorry. No posts matching your criteria!</strong>';

Nous définissons six attributs de code court que nous utilisons pour définir un tableau de paramètres, qui est finalement transmis à la fonction WordPress get_posts. Si $custom_posts n’est pas vide, alors un cycle foreach génère le HTML d’une liste non ordonnée d’éléments.

Maintenant, vous et les auteurs de votre blog pouvez inclure des listes de publications en utilisant un code court comme le suivant :

[kinsta_get_posts post_type="book" book_category="sci-fi" numberposts="4" price_min=1 price_max=250]

Bien sûr, vous pouvez changer le tableau d’arguments comme vous le souhaitez et exécuter vos tests dans n’importe quelle publication ou page de votre site de développement.

Une liste avancée des publications construite avec la fonction get_posts
Une liste avancée des publications construite avec la fonction get_posts

Résumé

WordPress get_posts est une fonction puissante qui permet aux développeurs d’inclure des listes de publications n’importe où sur l’interface publique de votre site WordPress. Elle utilise WP_Query mais est plus facile à utiliser et est préférable à WP_Query quand vous avez juste besoin de listes de publications. Quoi qu’il en soit, une référence directe à WP_Query est recommandée lorsque vous avez besoin d’afficher des publications dans une Loop.

Donc, construisez vos listes, testez votre code, et quand vous êtes sûr qu’il fonctionne bien, alors (et seulement alors) poussez-le sur votre site en production (mais effectuez d’abord une sauvegarde).

Nous aimerions maintenant vous lire. Quelle est votre expérience avec la fonction get_posts de WordPress ? Avez-vous des cas d’utilisation à partager avec nous ? Faites-le dans les commentaires ci-dessous !

Carlo Daniele Kinsta

Carlo is a passionate lover of webdesign and front-end development. He has been playing with WordPress for more than 20 years, also in collaboration with Italian and European universities and educational institutions. He has written hundreds of articles and guides about WordPress, published both on Italian and international websites, as well as on printed magazines. You can find him on LinkedIn.