La funzione get_posts di WordPress è una potente funzione che consente agli sviluppatori di recuperare parti di contenuto dal database di WordPress. Potete specificare i post, le pagine e i custom post type che state cercando, ottenere il vostro result set personalizzato, quindi filtrare e ordinare gli elementi come un ninja di PHP/MySQL.

Ma non spaventatevi se non siete professionisti del PHP perché ci sono innumerevoli tutorial PHP che potete guardare o leggere per imparare il linguaggio. Vi serve solo un po’ di conoscenza del PHP per creare liste personalizzate di post da visualizzare sul vostro sito web, dato che la funzione get_posts mantiene una serie di parametri che permettono di costruire query semplici o avanzate.

Utilizzare la funzione get_posts di WordPress consiste in una procedura in due passaggi:

  • Innanzitutto, dovete creare la vostra query personale. In realtà, non sembrerà una query MySQL e non dovrete scrivere alcuna istruzione SELECT. Dovete solo definire un array di parametri e passarlo alla funzione get_posts. WordPress lo converte in una query MySQL effettiva e sicura, la esegue sul database e restituisce un array di post.
  • Di seguito, dovrete iterare il risultato restituito da get_posts con un ciclo foreach.

Detto questo, in questo post analizzeremo innanzitutto i concetti chiave sopra menzionati; vedremo in particolare come funziona get_posts, come creare una query personalizzata e come mostrare i dati sul fronte del sito.
Quindi, offrirò un esempio dal mondo reale con uno snippet di codice che potete prelevare, modificare e utilizzare nel vostro ambiente di prova per i vostri test e l’attività di sviluppo.

Nota: di solito distinguiamo tra post, pagine e tipi di post personalizzati. In questo articolo, utilizziamo il termine ‘post’ per intendere sia i normali articoli del blog, sia le pagine e i custom post type. Tutti questi tipi di post sono memorizzati nella tabella ‘wp_posts’ del database. La differenza tra i tipi di post è nel valore del campo ‘post_type’. Dal punto di vista dello sviluppatore, post, pagine e tipi di post personalizzati sono tutti post.

Introduzione alla Funzione get_posts di WordPress

Il Codex descrive la funzione get_posts come segue:

Recupera un array degli ultimi post, o dei post corrispondenti ai criteri indicati.

Possiamo utilizzare get_posts questo modo:

$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 funzione qui sopra recupera l’ultimo post nella categoria specificata (di default 'post_type' è 'post') e restituisce un array di oggetti $post. È possibile scorrere l’array per visualizzare i post sullo schermo. È abbastanza facile, vero?

get_posts utilizza WP_Query per recuperare gli elementi post e accetta come argomento un array degli stessi parametri disponibili in WP_Query (con poche eccezioni). Quindi abbiamo un lungo elenco di variabili a nostra disposizione per creare le nostre query. Questi parametri sono raggruppati nelle seguenti 15 categorie:

  • Parametri Autore
  • Parametri di Categoria
  • Parametri di Tag
  • Parametri di Tassonomia
  • Parametri di Ricerca
  • Parametri di Articoli e Pagine
  • Parametri di Password
  • Parametri di Custom Post Type
  • Parametri Order e Orderby
  • Parametri Data
  • Parametri dei Custom Field (post meta)
  • Parametri relativi ai Permessi
  • Parametri Mime Type
  • Parametri di Cache
  • Parametri dei Campi Restituiti

Una rapida occhiata all’elenco qui sopra può darvi un’idea della varietà di query personali che potete creare ed eseguire sul database di WordPress. Quindi, conosciamo da vicino i parametri delle query e iniziamo a creare i nostri elenchi di post.

Come Creare Query con i Parametri di get_posts

Ogni categoria di parametri si riferisce alla stessa informazione. Ad esempio, possiamo creare una query per recuperare articoli dall’autore specificato, o escludendo l’autore specificato, definendo l’autore per ID o nicename. Allo stesso modo, possiamo creare query per recuperare post per categoria, tag, tassonomia, data, campi personalizzati e altro ancora.

Come Utilizzare i Parametri per Creare Semplici Query

Molti parametri possono essere utilizzati in modo simile, indipendentemente dalla categoria di appartenenza. Ad esempio, i seguenti parametri consentono di interrogare il database per autore/i dei post:

  • author (int) – ID autore
  • author_name (string) – user_nicename dell’autore
  • author__in (array) – un array di ID di più autori
  • author__not_in (array) – un array degli ID di più autori da escludere dal result set

Come possiamo utilizzare questi parametri?

Nell’esempio che segue, il parametro 'author' specifica che vogliamo i post del blog più recenti scritti dall’autore con ID = 1:

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

Lo stesso parametro ‘author’ permette di interrogare il database in diversi modi:

// 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 ) );

Quindi, a seconda del valore del parametro, otterrete un risultato con un singolo autore (integer), da più autori (un elenco di valori separati da virgola) o escludendo un autore (valori negativi).

Altri parametri offrono maggiore flessibilità. Ad esempio, la seguente chiamata a get_posts restituisce un array degli ultimi post di più autori:

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

E possiamo anche escludere più autori:

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

Allo stesso modo, possiamo utilizzare parametri di categoria, parametri di tag, parametri di post, con alcune differenze specifiche. Vediamo, ad esempio, i parametri di categoria:

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

Ad ogni modo, non tutti i parametri sono facili da usare come questi. Inoltre, possiamo utilizzare parametri di categoria, parametri dei post, parametri mime type, ecc. tutti in una sola query. Ciò significa che abbiamo un controllo granulare sugli elementi del result set, e che possiamo costruire query sempre più avanzate basate contemporaneamente su tipi di post, tassonomie personalizzate e custom field, tutti insieme.

E allora immergiamoci più a fondo!

Come Creare Query Avanzate in WordPress

Facciamo un passo avanti con una query più avanzata basata su custom post type e custom taxonomy. Supponiamo di avere il seguente tipo di post:

nome: book
nome tassonomia: book_category, book_author
supporto per: title, editor, thumbnail, excerpt, custom-fields

Custom Post Type e Custom Taxonomy

Supponiamo di voler un elenco dei libri più recenti nella custom taxonomy specificata book_category. Ecco l’array di argomenti:

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

Gli argomenti qui sopra dicono semplicemente a WordPress di recuperare tutti i libri nella 'book_category' con termine 'sci-fi'.

Il parametro 'tax_query' accetta un array di array di argomenti (cioè un array di array). Questi array nidificati consentono di creare query molto complesse basate su più tassonomie, come mostrato in questo esempio:

$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
		)
	)
);

Questi parametri ci consentono di recuperare un elenco degli ultimi 10 tipi di post 'book' in 'book_category', scritti da 'book_author' avente ID #22. Il parametro 'relation' imposta la relazione logica tra tutte le tassonomie elencate in 'tax_query'. Sopra abbiamo impostato il valore su AND perché dobbiamo recuperare tutti i libri appartenenti alla categoria 'sci-fi' e (AND) scritti dall’autore #22.

Come Creare Meta Query Utilizzando Parametri di Custom Field

Occasionalmente, potrebbe essere necessario creare elenchi di post in base a chiave e/o valore di uno specifico custom field.

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

Questi parametri ci consentono di recuperare tutti i post in base alla chiave e al valore del custom field. 'meta_compare' imposta l’operatore richiesto per testare il valore del parametro 'meta_value'. Qui 'meta_value' è '=', che è anche il valore predefinito.

I valori disponibili sono '=', '!=', '>', '>=', '<', '<=', 'LIKE', 'NOT LIKE', 'IN', 'NOT IN', 'BETWEEN', 'NOT BETWEEN', 'NOT EXISTS', 'REGEXP', 'NOT REGEXP', 'RLIKE'..

Questo è un esempio piuttosto semplice, possiamo creare query più avanzate. Nel prossimo esempio, interroghiamo il database per i libri fantasy pubblicati dopo il 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'
		)
	)
);

E possiamo andare ancora oltre. Nel prossimo esempio mixiamo un post con una custom taxonomy e due custom field:

$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',
		)
	)
);

Qui abbiamo impostato una serie di parametri per recuperare un elenco di libri fantasy pubblicati dopo il 2010 che costano BETWEEN $10 e $25.

Potete vedere che il parametro 'meta_query' funziona in modo molto simile al parametro 'tax_query'. Accetta un array di array, permettendoci di creare query avanzate basate su più coppie meta key/value. Per un elenco completo dei parametri della query e un buon numero di esempi, si veda la documentazione di WP_Query.

Perché get_posts è Si Limita a 5 Post di WordPress?

La funzione get_posts accetta gli stessi argomenti di WP_Query::parse_query() (vedi il Codex), ma alcuni parametri specifici la rendono leggermente diversa da un oggetto WP_Query.

Magari non avete utilizzato il parametro 'numberposts' nelle vostre query e vi stai chiedendo perché vedete solo 5 elementi nella vostra lista.

Di default, il numero di post che avete impostato nella pagina di amministrazione Impostazioni → Lettura determina il numero di post che devono essere recuperati da una query di WordPress. Tuttavia, se non si specifica un valore personalizzato per 'numberposts' o 'posts_per_page', get_posts restituisce un numero diverso di post.

  • 'numberposts' è il numero complessivo di post da recuperare. È un alias di 'posts_per_page' di WP_Query, ma c’è una differenza tra i due: di default, il numero di post da recuperare quando si utilizza get_posts è 5 , mentre 'posts_per_page' di WP_Query è impostato di default al numero di post per pagina del vostro blog WordPress. Potete sovrascrivere il valore predefinito impostando un valore personale per 'numberposts' o 'posts_per_page' nell’array di argomenti.

Oltre a 'numberposts', sono specifici di get_posts i parametri che seguono:

  • 'category' è un elenco separato da virgole di ID di categoria. È un alias del parametro 'cat' di WP_Query.
  • 'include' è un elenco separato da virgole di ID di post. È un alias del parametro 'post__in' di WP_Query.
  • 'exclude' è un elenco separato da virgole di ID di post.
  • 'suppress_filters' specifica se sopprimere i filtri. In get_posts, questo parametro è di default su true, mentre è impostato su false in WP_Query (si veda il Track).

La funzione get_posts è definita in wp-includes/post.php. Potete approfondire il funzionamento di get_posts analizzando il codice sorgente sul Track (WordPress 5.2) o nella vostra installazione locale di WordPress.

Ordinare gli Elementi

'orderby' e 'order' ordinano gli elementi del result set. Potete ordinare i post per 'ID', 'author', 'title', 'name', 'type', 'date', 'modified', 'parent', 'rand', 'comment_count' e in molti altri modi, in ordine crescente o decrescente.

Se avete una query semplice, dovete solo impostare un valore per 'order' e 'orderby'. Nell’esempio che segue, i post sono disposti in ordine crescente:

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

È abbastanza semplice. E se avessimo una query avanzata? Vale a dire: possiamo ordinare gli elementi in base a uno o più valori di custom field in una meta query avanzata?

WordPress 4.0 e WordPress 4.2 hanno apportato importanti miglioramenti ai parametri 'orderby' e 'meta_query'. Ora abbiamo a disposizione una nuova sintassi per l’ordinamento in base a specifiche clausole di una meta query. Grazie alla nuova sintassi, possiamo utilizzare degli indici per creare riferimenti dal parametro 'orderby' a clausole specifiche della meta query.

Grazie a questi miglioramenti, la meta query dell’esempio visto sopra può essere scritta come segue:

$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',
);

Nell’esempio qui sopra abbiamo ordinato gli elementi per 'price_clause'.

E possiamo fare ancora di più. A partire da WordPress 4.0, possiamo passare a get_posts un array di indici di meta query anziché un singolo indice, come vediamo nell’esempio che segue:

$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' ),
);

Congratulazioni, avete creato una meta query avanzata e ordinato i risultati prima per 'price_clause' in ordine crescente, quindi per 'year_clause' in ordine decrescente.

Vedi l’elenco completo delle opzioni di ordinamento nel Codex.

È il momento per noi di visualizzare i dati sulla pagina frontale.

Lettura consigliata: Come creare e utilizzare facilmente una pagina phpinfo.

Come Visualizzare i Dati Forniti da get_posts

La funzione get_posts di WordPress restituisce un array di oggetti WP_Post che danno accesso a numerose variabili per ogni post selezionato memorizzato nella tabella del database 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
WordPress get_posts: tabella wp_posts
Struttura della tabella wp_posts in phpMyAdmin

Potete accedere facilmente a questi dati con un ciclo foreach come il seguente:

$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>';

Se get_posts trova almeno un post, restituisce un array di elementi tra cui possiamo iterare per mostrare il titolo del post e un link al post originale. Abbiamo usato la funzione get_permalink per recuperare il permalink del post, dato che non abbiamo una variabile WP_Post corrispondente.

È abbastanza facile, ma come possiamo implementare questo codice per creare i nostri elenchi personalizzati di post usando la funzione get_posts di WordPress?

Potete mostrare elenchi di post sulle vostre pagine in molti modi.

Un Esempio Reale: Visualizzare un Elenco di Post Altamente Personalizzato con un Shortcode Personale

Vi mostrerò come creare un semplice e veloce shortcode per inserire i vostri contenuti. Tuttavia, qui non approfondirò l’argomento shortcode, in quanto abbiamo già affrontato questo argomento in un post precedente.

Prima di tutto, create una nuova directory nella cartella wp-content/plugins della vostra installazione locale di WordPress o in un ambiente di staging. In questo esempio, ho chiamato la directory kinsta-shortcodes.

In wp-content/plugins/kinsta-shortcodes/ create un file .php con lo stesso nome della nuova directory: kinsta-shortcodes.php.

Aprite il nuovo file nel vostro editor di testo preferito e inserite la seguente intestazione:

<?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/
*/

Ora abbiamo un bel plugin nuovo nuovo, ma che non fa ancora nulla. Andate nella pagina di amministrazione Plugin nella dashboard di WordPress e attivate il nuovo plugin assicurandovi di di aver impostato WP_DEBUG su true nel vostro file wp-config.php.

La vostra sandbox è ora pronta per i vostri hack. Il passo successivo è registrare un hook per uno shortcode personale:

/**
 * 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_posts è il nome dello shortcode e kinsta_get_posts_cb è la callback definita di seguito:

/**
 * 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>';

Abbiamo impostato sei attributi di shortcode che utilizziamo per definire un array di parametri, che viene infine passato alla funzione get_posts di WordPress. Se $custom_posts non è vuoto, un ciclo foreach genera l’HTML di un elenco non ordinato di elementi.

Ora voi e gli autori del vostro blog potete includere elenchi di post utilizzando uno shortcode come quello che segue:

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

Ovviamente, potete modificare l’array di argomenti ed eseguire i test su qualsiasi post o pagina del vostro sito di sviluppo.

elenco avanzato di post
Un elenco avanzato di post generato con la funzione get_posts

Riepilogo

La funzione get_posts di WordPress è una potente funzione che consente agli sviluppatori di includere elenchi di post ovunque sul frontend del proprio sito WordPress. Utilizza WP_Query, ma è più facile da usare di WP_Query ed è preferibile quando avete bisogno di elenchi di post. Ad ogni modo, un riferimento diretto a WP_Query è consigliabile quando è necessario visualizzare post in un Loop.

Allora, create i vostri elenchi, provate il vostro codice e, quando siete sicuri che funzioni bene, allora (e solo allora) mettetelo in produzione (ma prima eseguite un backup).

Ora vorremmo sentire voi. Qual è la vostra esperienza con la funzione get_posts di WordPress? Avere dei casi d’uso da condividere con noi? Fatelo nei commenti qui sotto!

Carlo Daniele Kinsta

Carlo è cultore appassionato di webdesign e front-end development. Gioca con WordPress da oltre 20 anni, anche in collaborazione con università ed enti educativi italiani ed europei. Su WordPress ha scritto centinaia di articoli e guide, pubblicati sia in siti web italiani e internazionali, che su riviste a stampa. Lo trovate su LinkedIn.