WordPress.org

Ready to get started?Download WordPress

Codex

it:Riferimento classi/WP Query

This article is marked as in need of editing. You can help Codex by editing it.

Contents

Descrizione

WP_Query è una classe definita in wp-includes/query.php che gestisce le complesse operazioni di richieste di articoli (o pagine) di un blog WordPress. Con wp-blog-header.php (o la classe WP nella Version 2.0) si forniscono all'oggetto $wp_query le informazioni che definiscono la richiesta corrente, quindi $wp_query determina il tipo di query con cui ha a che fare (probabilmente un archivio di categoria, un archivio per data, un feed o una ricerca) e recupera gli articoli richiesti. Con la richiesta vengono mantenute molte altre informazioni che potranno essere recuperate successivamente.

Interagire con WP_Query

La maggior parte delle volte è possibile trovare le informazioni desiderate senza dover gestire le funzioni della classe e le variabili globali. Vi sono un insieme di funzioni che è possibile richiamare ovunque che permettono di ottenere le informazioni desiderate.

Vi sono due scenari nei quali si desidererà utilizzare WP_Query. Il primo è quello nel quale si desidera scoprire con quale tipo di richiesta abbia attualmente a che fare WordPress. Le proprietà $is_* sono studiate per fornire queste informazioni: utilizzare i Conditional Tags per interagire con queste cose. Questo è lo scenario più comune per chi scrive plugin (il secondo normalmente si applica a chi scrive temi).

Il secondo scenario è durante Il Loop. WP_Query fornisce numerose funzioni per le operazioni più comuni con The Loop. Per cominciare, have_posts(), che richiama $wp_query->have_posts(), viene chiamato per verificare che vi siano articoli da visualizzare. Se ve ne sono inizia un ciclo while, utilizzando have_posts() come condizione. Questo fa si che si ripeta il ciclo sino a quando vi sono articoli da visualizzare. In ciascuna interazione viene chiamata la funzione the_post(), che richiama $wp_query->the_post() la quale imposta le variabili interne a $wp_query e la variabile globale $post (sulla quale i Template Tags si basano). Queste sono le funzioni che si dovrebbero utilizzare quando si scrive un tema che necessita di un ciclo. Si veda anche Il Loop e The Loop in Action per avere maggiori informazioni sul funzionamento.

Nota: Se si utilizza the_post() nella propria query occorre eseguire wp_reset_postdata() subito dopo per far si che i Template Tags utilizzino nuovamente l'articolo corrente della query principale.

Utilizzo

<?php

// La Query
$the_query = new WP_Query( $args );

// Il Loop
while ( $the_query->have_posts() ) :
	$the_query->the_post();
	echo '<li>' . get_the_title() . '</li>';
endwhile;

// Ripristina Query & Post Data originali
wp_reset_query();
wp_reset_postdata();


/* La seconda Query (senza variabili globali) */
$query2 = new WP_Query( $args2 );

// Il secondo Loop
while( $query2->have_posts() ):
	$query2->next_post();
	echo '<li>' . get_the_title( $query2->post->ID ) . '</li>';
endwhile;

// Ripristina Query & Post Data originali
wp_reset_query();
wp_reset_postdata();

?>

Metodi e proprietà

Questa è la documentazione formale di WP_Query. Non è possibile modificare direttamente le proprietà ma si dovranno utilizzare dei metodi. Si veda anche Interagire con WP_Query per alcune utili funzioni per evitare di pasticciare con le funzioni interne alla classe e le variabili globali.

Proprietà

$query
mantiene la stringa della query passata all'oggetto $wp_query dalla classe WP.
$query_vars
Un array associativo contenente la $query dissezionata: un array delle variabili della query ed i rispettivi valori.
$queried_object
Applicabile se la richiesta è una categoria, un autore, un permalink o una pagina. Contiene le informazioni della categoria, dell'autore, dell'articolo o della Pagina richiesti.
$queried_object_id
Se la richiesta è una categoria, un autore, un articolo / pagina, contiene l?ID corrispondente.
$posts
Viene riempito con gli articoli richiesti prelevati dal database.
$post_count
Il numero di articoli che vengono visualizzati.
$found_posts
Il numero totale di articoli recuperati che corrispondono ai parametri della query corrente
$max_num_pages
Il numero totale di pagine. È il risultato di $found_posts / $posts_per_page
$current_post
(disponibile durante Il Loop) Indice dell'articolo attualmente visualizzato.
$post
(disponibile durante Il Loop) L'articolo correntemente visualizzato.
$is_single, $is_page, $is_archive, $is_preview, $is_date, $is_year, $is_month, $is_time, $is_author, $is_category, $is_tag, $is_tax, $is_search, $is_feed, $is_comment_feed, $is_trackback, $is_home, $is_404, $is_comments_popup, $is_admin, $is_attachment, $is_singular, $is_robots, $is_posts_page, $is_paged
Booleani che indicano di quale tipo di richiesta si tratta. I primi tre ad esempio rappresentano rispettivamente 'è un permalink?', 'è una Pagina?', 'è un qualche tipo di pagina di arcvhivio?'.

Metodi

(Una e commerciale (ampersand - &) prima del nome di un metodo indica che viene returns by reference.)

init()
Inizializza l'oggetto, imposta tutte le proprietà a null, zero o falso.
parse_query( $query )
Prende la stringa di query che definisce la rischiesta, la analizza e popola tutte le proprietà ad esclusione di $posts, $post_count, $post e $current_post.
parse_query_vars()
Rianalizza la vecchia stringa di query.
get( $query_var )
Recupera una variabile di query col nome indicato.
set( $query_var, $value )
Imposta una variabile di query col nome indicato ad un valore specifico.
&get_posts()
Recupera dal database e restituisce gli articoli richiesti. Inoltre popola $posts e $post_count.
next_post()
(da utilizzare con IlLoop) Avanza all'articolo successivo in $posts. Incrementa $current_post ed imposta $post con l'oggetto dell'articolo corrente (nota: non imposta la variabile globale $post solo la variabile di istanza dell'oggetto WP_Query.) Restituisce l'oggetto corrispondente all'articolo corrente.
the_post()
(da utilizzare con Il Loop) Avanza all'articolo successivo ed imposta la variabile globale $post.
have_posts()
(da utilizzare con Il Loop, o subito prima del The Loop) Determina se vi sono ancora articoli da visualizzare.
rewind_posts()
Azzera $current_post e $post.
&query( $query )
Chiama parse_query() e get_posts(). Restituisce il risultato di get_posts().
get_queried_object()
Imposta $queried_object se non ancora impostato e lo restituisce.
get_queried_object_id()
Imposta $queried_object_id se non ancora impostato e lo restituisce.
WP_Query( $query = '' ) (costruttore)
Se si fornisce una stringa di query chiama query() utilizzando tale stringa.

Parametri

Parametri Autore

Visualizza gli articoli associati ad un determinato autore.

  • author (int) - utilizza l'id autore.
  • author_name (string) - utilizza 'user_nicename' (NON il nome).

Visualizza gli articoli di un Autore

Visualizza gli articoli di un autore utilizzando l'id autore:

$query = new WP_Query( 'author=123' );

Visualizza gli articoli di un autore utilizzando il 'user_nicename' dell'autore:

$query = new WP_Query( 'author_name=rami' );

Visualizza gli articoli di diversi Autori

Visualizza gli articoli da diversi autori specifici:

$query = new WP_Query( 'author=2,6,17,38' );

Esclude gli articoli appartenenti ad un Autore

Visualizza tutti gli articoli eccetto quelli di un autore(singolo) mettendo come prefisso all'id un segno '-' (meno):

$query = new WP_Query( 'author=-12' );

Paramentri di categoria

Visualizza gli articoli associati a determinate categorie.

  • cat (int) - utiliza l'id di categoria.
  • category_name (stringa) - utilizza l'abbreviazione (slug) di categoria (NON il nome).
  • category__and (array) - utilizza l'id di categoria.
  • category__in (array) - utilizza l'id di categoria.
  • category__not_in (array) - utilizza l'id di categoria.

Mostra articoli di una categoria

Visualizza gli articoli che hanno questa categoria (e ogni figlio di questa categoria), using category id:

$query = new WP_Query( 'cat=4' );

Visualizza gli articoli che hanno questa categoria (e ogni figlio di questa categoria), using category slug:

$query = new WP_Query( 'category_name=staff' );

Mostra articoli di varie categorie

Visualizza gli articoli che hanno queste categorie, utilizzando l'id di categoria:

$query = new WP_Query( 'cat=2,6,17,38' );

Visualizza gli articoli che hanno queste categorie, utilizzando l'abbreviazione (slug) di categoria:

$query = new WP_Query( 'category_name=staff,news' );

Escludere articoli appartenenti ad una categoria

Visualizza tutti gli articoli meno quelli che hanno una categoria mettendo come prefisso ai loro id un segno '-' (meno).

$query = new WP_Query( 'cat=-12,-34,-56' );

Gestione di categorie multiple

Visualizza gli articoli che sono in categorie multiple. L'esempio seguente visualizza gli articoli che appartengono sia categoria 2 che 6:

$query = new WP_Query( array( 'category__and' => array( 2, 6 ) ) );

Per visualizzare articoli dalla categoria 2 OPPURE 6, è possibile utilizzare cat come spiegato in precedenza oppure utilizzare category__in (si noti che i questo caso non verranno visualizzati articoli appartenenti ai figli di queste categorie):

$query = new WP_Query( array( 'category__in' => array( 2, 6 ) ) );

È anche possibile escludere categorie multiple in questo modo:

$query = new WP_Query( array( 'category__not_in' => array( 2, 6 ) ) );

Parametri dei tag

Mostra gli articoli associati a determinati tag.

  • tag (stringa) - utilizza l'abbreviazione (slug) del tag.
  • tag_id (int) - utilizza l'id del tag.
  • tag__and (array) - utilizza gli id dei tag.
  • tag__in (array) - utilizza gli id dei tag.
  • tag__not_in (array) - utilizza gli id dei tag.
  • tag_slug__and (array) - utilizza l'abbreviazione (slug) dei tag.
  • tag_slug__in (array) - utilizza l'abbreviazione (slug) dei tag.

Mostra gli articoli per un tag

Visualizza gli articoli che hanno questo tag utilizzando l'abbreviazione del tag:

$query = new WP_Query( 'tag=cooking' );

Visualizza gli articoli che hanno questo tag utilizzando l'id del tag

$query = new WP_Query( 'tag_id=13' );

Mostra gli articoli con diversi tag

Visualizza gli articoli che hanno "uno" di questi tag:

$query = new WP_Query( 'tag=bread,baking' );

Visualizza gli articoli che hanno "tutti" questi tag:

$query = new WP_Query( 'tag=bread+baking+recipe' );

Gestione tag multipli

Visualizza gli articoli sono contrassegnati sia dal tag di id 37 che dal tag di id 47:

$query = new WP_Query( array( 'tag__and' => array( 37, 47 ) ) );

Per visualizzare gli articoli che abbiano o il di id 37 oppure 47 è possibile utilizzare tag come spiegato in precedenza oppure specificarlo esplicitamente usando tag__in:

$query = new WP_Query( array( 'tag__in' => array( 37, 47 ) ) );

Visualizza gli articoli che nessuno dei due tag di id 37 e 47:

$query = new WP_Query( array( 'tag__not_in' => array( 37, 47 ) ) );

I parametri tag_slug__in e tag_slug__and operano praticamente nello stesso modo ma utilizzano l'abbreviazione (slug) del tag.

Parametri di tassonomia

Mostra gli articoli associati a determinate tassonomie.

  • {tax} (stringa) - utilizza l'abbreviazione della tassonomia. Deprecata dalla versione Version 3.1 in favore di 'tax_query'.
  • tax_query (array) - utilizza i paramentri della tassonomia (disponibile dalla Version 3.1).
    • taxonomy (stringa) - Tassonomia.
    • field (stringa) - Seleziona il temine della tassonomia per ('id' o 'slug')
    • terms (int/stringa/array) - Termine/i della tassonomia.
    • include_children (booleano) - Indic se includere o meno i figliper le tassonomie gerarchiche. Valore predefinito impostato a true.
    • operator (stringa) - Operatore di verifica. I valori possibili sono 'IN', 'NOT IN', 'AND'.

Nota importante: tax_query accetta un array di parametri di arrays di argomenti di tax query (prende un array di array) - si veda il secondo esempio qua sotto. Questo construtto permette di interrogare tassonomie multiple utilizzando il parametro relation nel primo array (quello più esterno) (outer) per descrivere la relazione booleana fra le varie query di tassonomia.

Dalla 3.5 è stato risolto un bug che restituiva inavvertitamente tutti gli articoli quando il risultato doveva essere vuoto.

Query di tassonomia semplice:

Visualizza gli articoli contrassegnati con bob nella tassonomia personalizzata persone:

$args = array(
	'post_type' => 'posts',
	'persone' => 'bob'
);
$query = new WP_Query( $args );

Visualizza gli articoli contrassegnati con bob nella tassonomia personalizzata persone utilizzando tax_query:

$args = array(
	'post_type' => 'posts',
	'tax_query' => array(
		array(
			'taxonomy' => 'persone',
			'field' => 'slug',
			'terms' => 'bob'
		)
	)
);
$query = new WP_Query( $args );

Gestione tassonomie multiple:

Visualizza articoli da diverse tassonomie personalizzate:

$args = array(
	'post_type' => 'posts',
	'persone' => 'bob',
	'lingua' => 'inglese'
);
$query = new WP_Query( $args );

Visualizza articoli da diverse tassonomie personalizzate utilizzando tax_query:

$args = array(
	'post_type' => 'posts',
	'tax_query' => array(
		'relation' => 'AND',
		array(
			'taxonomy' => 'genere_film',
			'field' => 'slug',
			'terms' => array( 'azione', 'commedia' )
		),
		array(
			'taxonomy' => 'attore',
			'field' => 'id',
			'terms' => array( 103, 115, 206 ),
			'operator' => 'NOT IN'
		)
	)
);
$query = new WP_Query( $args );

Visualizza articoli che sono nella categoria citazioni OPPURE che sono nel formato quote:

$args = array(
	'post_type' => 'posts',
	'tax_query' => array(
		'relation' => 'OR',
		array(
			'taxonomy' => 'category',
			'field' => 'slug',
			'terms' => array( 'citazioni' )
		),
		array(
			'taxonomy' => 'post_format',
			'field' => 'slug',
			'terms' => array( 'post-format-quote' )
		)
	)
);
$query = new WP_Query( $args );

Parametri di ricerca

Visualizza gli articoli in base ad una ricerca per parole chiave.

  • s (stringa) - Parola chiave di ricerca.

Mostra gli articoli in base ad una chiave di ricerca

Visualizza gli articoli che corrispondono alla ricerca del termine "keyword":

$query = new WP_Query( 's=keyword' );

Parametri Articolo e Pagina

Visualizza il contenuto in base ai parametri di articolo e di pagina.

  • p (int) - utilizza l'id dell'articolo.
  • name (string) - utilizza l'abbreviazione (slug) dell'articolo.
  • page_id (int) - utilizza l'id della pagina.
  • pagename (string) - utilizza l'abbreviazione (slug) della pagina.
  • post_parent (int) - utilizza l'id della pagina. Restituisce solele Pagine figlie.
  • post__in (array) - utilizza l'id dell'articolo. Specifica quali articoli recuperare.
  • post__not_in (array) - utilizza l'id dell'articolo. Specifica quali articolo NON recuperare.

Mostra Articolo/Pagina per ID

Visualizza un articolo in base al suo ID:

$query = new WP_Query( 'p=7' );

Visualizza una pagina in base al suo ID::

$query = new WP_Query( 'page_id=7' );

Mostra Articolo/Pagina per abbreviazione (slug)

Visualizza un articolo in base alla sua abbreviazione (slug):

$query = new WP_Query( 'name=informazioni-su-di-me' );

Visualizza una pagina in base alla sua abbreviazione (slug):

$query = new WP_Query( 'pagename=contatti' );

Mostra i figli di una Pagina

Visualizza le pagine figlie utilizzando l'abbreviazione della apgina genitrice e figlia, separate da una barra (es. 'abbreviazione_genitore/abbreviazione_figlio'):

$query = new WP_Query( 'pagename=contattaci/canada' );

Visualizza le pagine figlie utilizzando l'ID della pagina madre:

$query = new WP_Query( 'post_parent=93' );

Visualizza solo le pagine principali escludendo tutte le pagine figlie:

$query = new WP_Query( 'post_parent=0' );

Gestione Articoli/Pagine multiple

Visualizza solo specifici articoli:

$query = new WP_Query( array( 'post_type' => 'page', 'post__in' => array( 2, 5, 12, 14, 20 ) ) );

Visualizza tutti gli articoli ma NON quelli specificati:

$query = new WP_Query( array( 'post_type' => 'post', 'post__not_in' => array( 2, 5, 12, 14, 20 ) ) );

Nota: non è possibile combinare 'post__in' e 'post__not_in' nella medesima query.

Parametri Tipo

Visualizza gli articoli associati a specifici tipi di articolo.

  • post_type (stringa / array) - utilizza i tipi di articolo. Recupera articoli di genere Post Types, il valore predefinito è 'post';
    • 'post' - un articolo.
    • 'page' - una pagina.
    • 'revision' - una revisione.
    • 'attachment' - un allegato. Di base WP_Query imposta 'post_status'=>'publish', ma gli allegati hanno un 'post_status'=>'inherit' quindi si dovrà impostare lo status a 'inherit' o 'any'.
    • 'any' - recupera tutti i tipi escluso le revisioni e le tipologie con 'exclude_from_search' impostate a vero.
    • Custom Post Types (es. film)

Visualizza articolo per tipo

Visualizza solo pagine:

$query = new WP_Query( 'post_type=page' );

Visualizza 'any' tipo di articolo (recupera qualiasi tipo escludendo le revisioni e le tipologie con 'exclude_from_search' impostate a TRUE):

$query = new WP_Query( 'post_type=any' );

Visualizza vari tipi di articolo, compresi i custom post types:

$query = new WP_Query( array( 'post_type' => array( 'post', 'page', 'film', 'libri' ) ) );

Parametri di stato

Visualizza articoli associati a determinati tipi di stato.

  • post_status (stringa / array) - utilizza lo stato degli articoli. Recuper gli articoli in base al Post Status, il valore predefinito è 'publish'.
    • 'publish' - un articolo o una pagina pubblicati.
    • 'pending' - articolo in attesa di revisione.
    • 'draft' - un articolo con lo stato di bozza.
    • 'auto-draft' - un articolo appena creato, senza alcun contenuto.
    • 'future' - un articolo da pubblicare in futuro.
    • 'private' - non visibile agli utenti che non sono autenticati.
    • 'inherit' - una revisione. si veda get_children.
    • 'trash' - articolo nel cestino (disponibile dalla Version 2.9).
    • 'any' - recupera qualsiaso stato eccetto quelli dei tipi di articolo con 'exclude_from_search' impostato a TRUE.

Visualizza articolo in base allo stato

Visualizza solo le bozze:

$query = new WP_Query( 'post_status=draft' );

Visualizza articoli con diversi stati:

$query = new WP_Query( array( 'post_status' => array( 'pending', 'draft', 'future' ) ) );

Visualizza tutti gli allegati:

$query = new WP_Query( array( 'post_status' => 'any', 'post_type' => 'attachment' ) );

Parametri di paginazione

  • nopaging (booleano) - visualizza tutti gli articoli o utilizza la paginazione. Il valore predefinito è 'false', utilizza la paginazione.
  • posts_per_page (int) - numero di articoli da visualizzare per ciascuna pagina (disponibile dalla Version 2.1, sostituita dal parametro showposts). Utilizzare 'posts_per_page'=>-1 per mostrare tutti gli articoli. Nota: se la quaery è in un feed, WordPress sovrascrive il parametro con quello memorizzato nella opzione 'posts_per_rss'. Per reimpostare il limite, si utilizzi il filtro 'post_limits' oppure filtrare su 'pre_option_posts_per_rss' e restituire -1
  • offset (int) - numero di articoli da scartare o ignorare. Nota: Impostando il parametro offset si ignorera il parametro paged.
  • paged (int) - numero di pagina. Visualizza gli articoli che normalmente appaiono nella pagina X quando si utilizza il link "Voci precedenti".
  • posts_per_archive_page (int) - numero di articoli da mostrare per ciascuna pagina - solo nelle pagine di archivio. Sovrascrive showposts e posts_per_page nelle pagine in cui is_archive() o is_search() sono vere

Mostrare x articoli per pagina

Visualizza 3 articoli per pagina:

$query = new WP_Query( 'posts_per_page=3' );

Mostrare tutti gli articoli

Visualizza tutti gli articoli su una singola pagina:

$query = new WP_Query( 'posts_per_page=-1' );

Visualizza tutti gli articoli disabilitando la paginazione:

$query = new WP_Query( 'nopaging=true' );

Scartare alcuni articoli

Visualizza gli articoli a partire dal quarto:

$query = new WP_Query( 'offset=3' ) );

Visualizza 5 articoli per pagina a partire da dopo i 3 articoli più recenti:

$query = new WP_Query( array( 'posts_per_page' => 5, 'offset' => 3 ) );

Mostrare articoli dalla pagina x

Visualizza gli articoli dalla pagina numero 6:

$query = new WP_Query( 'paged=6' );

Mostrare articoli dalla pagina corrente

Visualizza gli articoli a partire dalla pagina corrente:

$query = new WP_Query( array( 'paged' => get_query_var( 'paged' ) ) );

Visualizza gli articoli a partire dalla pagina corrente ed imposta il parametro 'paged' ad 1 quando la variabile di query non è impostata (prima pagina).

$paged = (get_query_var('paged')) ? get_query_var('paged') : 1;
$query = new WP_Query( array( 'paged' => $paged ) );

Nota sulla paginazione: Utilizzare get_query_var('page'); se si desidera che la query funzioni nel Template di pagina che è stato impostato come pagina iniziale statica. La variabile di query 'page' contiene il numero di pagina per un singolo articolo o pagina che contiene il Quicktag <!--nextpage--> nel contenuto dell'articolo.

Visualizza gli articoli della pagina corrente su una pagina iniziale statica:

$paged = (get_query_var('page')) ? get_query_var('page') : 1;
$query = new WP_Query( array( 'paged' => $paged ) );

Parametri Order & Orderby

Ordinanono gli articoli recuperati.

  • order (stringa) - Determina l'ordinamento ascendente o discendente del parametro 'orderby'. Valore predefinito 'DESC'.
    • 'ASC' - ordine ascendente dal valore più piccolo a quello più grande (1, 2, 3; a, b, c).
    • 'DESC' - ordine discendente dal valore più grande a quello più piccolo (3, 2, 1; c, b, a).
  • orderby (stringa) -Ordina gli articoli recuperati in base al parametro. Valore predefinito 'date'.
    • 'none' - Nessun ordinamento (disponibile dalla Version 2.8).
    • 'ID' - Ordina per id artciolo. Si noti il maiuscolo.
    • 'author' - Ordina per autore.
    • 'title' - Ordina per titolo.
    • 'name' - Ordina per nome articolo (abbreviazione (slug) dell'articolo).
    • 'date' - Ordina per data.
    • 'modified' - Ordina per data di ultima modifica.
    • 'parent' - Ordina in base all'id dell'articolo/pagina genitore.
    • 'rand' - Ordina casualmente.
    • 'comment_count' - Ordina in base al numero dei commenti (disponibile dalla Version 2.9).
    • 'menu_order' - Ordina in base all'odinamento Pagina. Utilizzato principalmente per Pages (il campo Ordine nel riquadro degli attributi nell'editor di Pagine) e per gli Allegati (il campi numerici interi nella finestra di dialogo Inserisci / Carica galleria media), ma può essere utilizzato per qualsiasi tipi di articolo con distinti valori di 'menu_order' (di base valgono tutti 0).
    • 'meta_value' - Si noti che una definizione 'meta_key=nomechiave' deve essere presente nella query. Si noti anche che l'ordinamento è alfabetico che è corretto per le stringhe (es. parole) ma può fornire risultati inaspettati per i numeri (es. 1, 3, 34, 4, 56, 6, ecc, anzichè 1, 3, 4, 6, 34, 56 come si si aspetterebbe). Utilizzare in questo caso 'meta_value_num' per i valori numerici.
    • 'meta_value_num' - Ordinamento per valori numerici dei metadati (disponibile dalla Version 2.8). Si noti che una definizione 'meta_key=nomechiave' deve essere presente nella query. Questo valore consente l'ordinamento numerico come indicato precedentemente in 'meta_value'.
    • 'post__in' - Mantiene l'ordine indicato degli ID fornito con l'array post__in array (disponibile dalla Version 3.5).

Mostrare articoli ordinati per titolo in ordine discendente

Visualizza gli articoli odinati in base al titolo in ordine discendente:

$query = new WP_Query( array ( 'orderby' => 'title', 'order' => 'DESC' ) );

Mostrare articoli casuali

Visualizza un articolo a caso:

$query = new WP_Query( array ( 'orderby' => 'rand', 'posts_per_page' => '1' ) );

Mostrare gli articoli più popolari

Visualizza gli articoli ordinati in base la numero dei commenti:

$query = new WP_Query( array( 'orderby' => 'comment_count' ) );

Mostrare dei prodotti ordinati in base al prezzo

Visualizza gli articoli di tipo 'Prodotto' ordinati in base al campo personalizzato 'Prezzo':

$query = new WP_Query( array ( 'post_type' => 'prodotto', 'orderby' => 'meta_value', 'meta_key' => 'prezzo' ) );

Valori multipli di 'orderby'

Visualizza le pagine ordinate in base al 'title' ed al 'menu_order'. (il titolo è predominante):

$query = new WP_Query( array( 'post_type' => 'page', 'orderby' => 'title menu_order', 'order' => 'ASC' ) );

'orderby' con 'meta_value' e tipi di articolo personalizzati

Visualizza gli articoli di tipo 'mio_tipo_di_articolo', ordinati per 'eta' e filtrati per mostrare solo le età 3 e 4 (utilizzando meta_query).

 $args = array(
   'post_type' => 'mio_tipo_di_articolo',
   'meta_key' => 'eta',
   'orderby' => 'meta_value_num',
   'order' => 'ASC',
   'meta_query' => array(
       array(
           'key' => 'eta',
           'value' => array(3, 4),
           'compare' => 'IN',
       )
   )
 );
 $query = new WP_Query($args);

Parametri articolo in evidenza

Mostra articoli in evidenza oppure li ignora.

  • ignore_sticky_posts (booleano) - ignora gli articoli in evidenzaoppure no (disponibile dalla Version 3.1, sostituito dal parametro caller_get_posts). Valore predefinito 0 - non ignora gli articoli in evidenza. Nota: ignora/esclude gli articoli in evidenza dall'essere inclusi all'inizio degli articoli restituiti, ma gli articoli in evidenza appariranno nell'ordine naturale dell'elenco degli articoli che viene restituito.

Mostrare gli articoli in videnza

Visualizza solo il primo articolo in evidenza:

$sticky = get_option( 'sticky_posts' );
$query = new WP_Query( 'p=' . $sticky[0] );

Visualizza solo il primo articolo in evidenza e se non ve ne è alcuno l'ultimo articolo pubblicato:

$args = array(
	'posts_per_page' => 1,
	'post__in'  => get_option( 'sticky_posts' ),
	'ignore_sticky_posts' => 1
);
$query = new WP_Query( $args );

Visualizza solo il primo articolo in evidenza, se non ve ne è alcuno non restituisce nulla:

$sticky = get_option( 'sticky_posts' );
$args = array(
	'posts_per_page' => 1,
	'post__in'  => $sticky,
	'ignore_sticky_posts' => 1
);
$query = new WP_Query( $args );
if ( $sticky[0] ) {
	// inserire il proprio codice...
}

Non mostrare gli articoli in evidenza

Esclude tutti gli articoli in evidenza dalla query:

$query = new WP_Query( array( 'post__not_in' => get_option( 'sticky_posts' ) ) );

Esclude gli articoli in evidenza di una categoria. Restituisce TUTTI gli articoli di una categoria ma non mette gli articoli in evidenza all'inizio dell'elenco. Gli 'articoli in evidenza' appariranno però nell'elenco nella loro posizione naturale in base all'ordinamento (es. per data):

$query = new WP_Query( array( 'ignore_sticky_posts' => 1, 'posts_per_page' => 3, 'cat' => 6 );

Esclude gli articoli in evidenza di una data categoria. Restituisce gli articoli appartenenti ad una categoria ma esclude completamente gli articoli in evidenza e gestisce correttamente le regole di paginazione:

$paged = get_query_var( 'paged' ) ? get_query_var( 'paged' ) : 1;
$sticky = get_option( 'sticky_posts' );
$args = array(
	'cat' => 3,
	'ignore_sticky_posts' => 1,
	'post__not_in' => $sticky,
	'paged' => $paged
);
$query = new WP_Query( $args );

Parametri di tempo

Mostrare gli articoli associati ad un certo periodo di tempo.

  • year (int) - anno a 4 cifre (es. 2011).
  • monthnum (int) - Numero del mese (da 1 a 12).
  • w (int) - Settimana dell'anno (da 0 a 53). Utilizza il comando MySQL WEEK. La modalità dipende dall'opzione "start_of_week" option.
  • day (int) - Giorno del mese (da 1 a 31).
  • hour (int) - Ora (da 0 a 23).
  • minute (int) - Minuto (da 0 a 60).
  • second (int) - Secondo (da 0 a 60).

Restituisce gli articoli per la data corrente:

$today = getdate();
$query = new WP_Query( 'year=' . $today["year"] . '&monthnum=' . $today["mon"] . '&day=' . $today["mday"] );

Restituisce gli articoli della settimana corrente:

$week = date('W');
$year = date('Y');
$query = new WP_Query( 'year=' . $year . '&w=' . $week );

Restituisce gli articoli datatti 20 Dicembre:

$query = new WP_Query( 'monthnum=12&day=20' );

Nota: Le query precedenti restituiscono articoli per una data specicifica, es. "Articli dell'anno X, mese X, giorno X". Non riescono ad estrarre articoli per un periodo di tempo relativo al presente, quindi query del tipo "Articoli degli ultimi 30 giorni" oppure "Articoli dell'ultimo anno" non sono possibili con le query di base e richiedono che gli articoli vengano filtrati per completare l'operazione ed ottenere i dati desiderati. Gli esempi precedenti utilizzano il filtro posts_where e possono essere modificate per la maggior parte delle query di tipo relativo.

Restituire gli articoli dal 1 marzo al 15 marzo 2010:

// Crea una nuova funzione di filtraggio che aggiunga una clausola where alla query
function filter_where( $where = '' ) {
	// articoli dal 1 marzo al 15 marzo 2010
	$where .= " AND post_date >= '2010-03-01' AND post_date < '2010-03-16'";
	return $where;
}

add_filter( 'posts_where', 'filter_where' );
$query = new WP_Query( $query_string );
remove_filter( 'posts_where', 'filter_where' );

Restituire articoli degli ultimi 30 giorni:

// Crea una nuova funzione di filtraggio che aggiunga una clausola where alla query
function filter_where( $where = '' ) {
	// posts in the last 30 days
	$where .= " AND post_date > '" . date('Y-m-d', strtotime('-30 days')) . "'";
	return $where;
}

add_filter( 'posts_where', 'filter_where' );
$query = new WP_Query( $query_string );
remove_filter( 'posts_where', 'filter_where' );

Restituire gli articoli più vecchi fra i 30 ed i 60 giorni

// Crea una nuova funzione di filtraggio che aggiunga una clausola where alla query
function filter_where( $where = '' ) {
	// articoli vecchi fra i 30 ed i 60 giorni
	$where .= " AND post_date >= '" . date('Y-m-d', strtotime('-60 days')) . "'" . " AND post_date <= '" . date('Y-m-d', strtotime('-30 days')) . "'";
	return $where;
}

add_filter( 'posts_where', 'filter_where' );
$query = new WP_Query( $query_string );
remove_filter( 'posts_where', 'filter_where' );

Parametri campi personalizzati

Mostrare articoli associati a determinati campi personalizzati.

  • meta_key (stringa) - Chiave del campo personalizzato.
  • meta_value (stringa) - Valore del campo personalizzato.
  • meta_value_num (numero) - Valore del campo personalizzato.
  • meta_compare (stringa) - Operatore con cui confrontare 'meta_value'. I possibili valori sono '!=', '>', '>=', '<' o '<='. Il valore predefinito è '='.
  • meta_query (array) - Parametri del campo personalizzato (disponiile dalla Version 3.1).
    • key (string) - Chiave del campo personalizzato.
    • value (string|array) - Valore del campo personalizzato (Nota: IL supporto all'array è limitato a comparare i valori con 'IN', 'NOT IN', 'BETWEEN' o 'NOT BETWEEN') (Questo valore può essere omesso quando si utilizza nella comparazione 'EXISTS' o 'NOT EXISTS' questa modalità è disponibile da WordPress 3.5)
    • compare (string) - Operatore di test. I valori possibili sono '=', '!=', '>', '>=', '<', '<=', 'LIKE', 'NOT LIKE', 'IN', 'NOT IN', 'BETWEEN', 'NOT BETWEEN', 'EXISTS' (solo in WP >= 3.5) e 'NOT EXISTS' (anch'esso solo in WP >= 3.5). Il valore predefinito è '='.
    • type (stringa) - Tipo di campo personalizzato. I possibili valori sono 'NUMERIC', 'BINARY', 'CHAR', 'DATE', 'DATETIME', 'DECIMAL', 'SIGNED', 'TIME', 'UNSIGNED'. Il valore predefinito è 'CHAR'.

Il 'type' DATE opera solo con il valore di 'compare' BETWEEN se la data è memorizzata nel formato YYYYMMDD e viene verificato con questo formato.

Una semplice query con campi personalizati:

Visualizza gli articoli dove la chiave del campo personalizzato è 'colore' indipendentemente dal valore del campo personalizzato:

$query = new WP_Query( 'meta_key=colore' );

Visualizza gli articoli dove il valore del campo personalizzato è 'blu' indipendentemente dal valore della chiave del campo personalizzato:

$query = new WP_Query( 'meta_value=blu' );

Visaulizza Pagine dove il valore del campo personalizzato è 'blu'indipendentemente dal valore della chiave del campo personalizzato:

$query = new WP_Query( 'meta_value=blue&post_type=page' );

Visualizza gli articoli dove la chiave del campo personalizzato è 'colore' ed il valore del campo personalizzato è 'blu':

$query = new WP_Query( array( 'meta_key' => 'colore', 'meta_value' => 'blu' ) );

Visualizza gli articoli dove la chiave del campo personalizzato è 'colore' ed il valore del campo personalizzato NON È 'blu':

$query = new WP_Query( array( 'meta_key' => 'colore', 'meta_value' => 'blu', 'meta_compare' => '!=' ) );

Visualizza 'prodotti' dove la chiave del campo personalizzato è 'prezzo' ed il valore del campo personalizzato è MINORE O UGUALE A 22.
Utilizzando il parametro 'meta_value' il valore di 99 verrà considerato maggiore di 100 poichè i dati sono memorizati come 'stringhe', e non 'numeri'. Per una comparazione numerica utilizare 'meta_value_num'.

$query = new WP_Query( array( 'meta_key' => 'prezzo', 'meta_value' => '22', 'meta_compare' => '<=', 'post_type' => 'prodotto' ) );

Visualizza gli articoli con un campo personalizzato di valore zero (0) idipendentemente dal valore della chiave del campo personalizzato:

$query = new WP_Query( array ( 'meta_value' => '_wp_zero_value' ) );

Gestione di un singolo campo personalizzato:

Visualizza gli articoli da un singolo campo personalizzato:

$args = array(
	'post_type' => 'prodotto',
	'meta_query' => array(
		array(
			'key' => 'colore',
			'value' => 'blu',
			'compare' => 'NOT LIKE'
		)
	)
);
$query = new WP_Query( $args );

(SI noti che meta_query si aspetta uan serie di array nidificati anche se si ha una singola query.)

Gestione di campi personalizzati multipli:

Visualizza articoli con diversi campi personalizzati:

$args = array(
	'post_type' => 'prodotto',
	'meta_query' => array(
		array(
			'key' => 'colore',
			'value' => 'blu',
			'compare' => 'NOT LIKE'
		),
		array(
			'key' => 'prezzo',
			'value' => array( 20, 100 ),
			'type' => 'numeric',
			'compare' => 'BETWEEN'
		)
	)
);
$query = new WP_Query( $args );

Visualizza articoli con meta key 'colore' NON UGUALE al valore 'blu' OPPURE meta key 'prezzo' con valori compresi FRA 20 e 100:

$args = array(
	'post_type' => 'prodotto',
	'meta_query' => array(
		'relation' => 'OR',
		array(
			'key' => 'colore',
			'value' => 'blu',
			'compare' => 'NOT LIKE'
		),
		array(
			'key' => 'prezzo',
			'value' => array( 20, 100 ),
			'type' => 'numeric',
			'compare' => 'BETWEEN'
		)
	)
);
$query = new WP_Query( $args );

Parametri sui permessi

  • perm (stringa) - Permessi utente.

Mostra gli articoli se l'utente ha le capacità appropriate:

Visualizza articoli pubblici e privati se l'utente dispone della capacita appropriata:

$query = new WP_Query( array( 'post_status' => array( 'publish', 'private' ), 'perm' => 'readable' ) );

Parametri di cache

Impedisce che i dati recuperati venfgano aggiunti alal cache.

  • cache_results (booleano) - Cache sulle informazioni degli articoli.
  • update_post_meta_cache (booleano) - Cache sulle informazioni dei metadati degli articoli.
  • update_post_term_cache (booleano) - Cache sulle informazioni dei termini associati agli articoli.

Visualizza gli articoli senza aggiungere le informazioni alla cache

Visualizza 50 articoli ma non aggiunge le informazioni sugli articoli alla cache:

$query = new WP_Query( array( 'posts_per_page' => 50, 'cache_results' => false ) );

Visualizza gli articoli senza aggiungere i metadati degli articoli alla cache

Visualizza 50 articoli ma non aggiunge le informazioni sui metadati degli articoli alla cache:

$query = new WP_Query( array( 'posts_per_page' => 50, 'update_post_meta_cache' => false ) );

Visualizza gli articoli senza aggiungere le informazioni sui termini degli articoli alla cache

Visualizza 50 articoli ma non aggiunge le informazioni sui termini degli articoli alla cache:

$query = new WP_Query( array( 'posts_per_page' => 50, 'update_post_term_cache' => false ) );

In un normale utilizzo non si ha solitamente necessità di utilizzare questo parametro, aggiungere alla cache è solitamente la cosa giusta da fare, tuttavia può essere utile in determinate circostanze. Un esempio di tali circostanze potrebbe essere quando si utilizza una WP_Query per recuperare un elenco di titoli di articoli e la loro URL per visualizzarli, ma nessun'altra informazione riguardante gli articoli verrà utilizzata ed i dati sulle tassonomie e sui metadati non sono necessari. Non caricando queste informazioni si risparmia tempo per le query SQL extra assolutamente non necessarie.

Nota: Se viene utilizzato un sistema di backend di cache di oggetti permanente (tipo memcached) questi parametri sono impostati automaticamente a falso perchè non vi è necessità di aggiornare la cache ad ogni caricamento pagina quando è presente una cache persistente.

Parametro campi da restituire

Imposta i valori di ritorno.

  • fields (stringa|array) - Quali campi restituire. Di base all.
    • 'ids' - Restituisce un array di ID di articoli.
    • 'id=>parent' - Restituisce un array associativo [ parent => ID, … ].
    • qualsiasi altro valore o un valore vuoto (predefinitio): restituisce un array di oggetti articolo

Filtri

  • posts_distinct - Modifica la clausola SQL 'DISTINCTROW' nella query che restituisce l'array degli articoli.
  • posts_groupby - Modifica la clausola SQL 'GROUP BY' nella query che restituisce l'array degli articoli.
  • posts_join - Modifica la clausola SQL 'JOIN' nella query che restituisce l'array degli articoli.
  • post_limits - Modifica la clausola SQL 'LIMIT' nella query che restituisce l'array degli articoli.
  • posts_orderby - Modifica la clausola SQL 'ORDER BY' nella query che restituisce l'array degli articoli.
  • posts_where - Modifica la clausola SQL 'WHERE' nella query che restituisce l'array degli articoli.
  • posts_join_paged - Modifica la paginazione degli articoli utilizzando la clausola 'JOIN' nella query che restituisce l'array degli articoli.
  • posts_where_paged - Modifica la paginazione degli articoli utilizzando la clausola 'WHERE' nella query che restituisce l'array degli articoli.
  • posts_clauses - Modifica tutte le clausole SQL precedenti in una sola volta. Fornisce un array di elementi che sono facilmente modificabili (disponibile dalla Version 3.1).

Si noti che vi sono altri filtri non in elenco. Essendo complesso mantenere sempre aggiornato il codex, analizzare la funzione get_posts(); dentro la classe WP_Query (/wp-includes/query.php) per vedere tutti i filtri disponibili.

File sorgente

WP_Query() si trova in wp-includes/query.php.

Risorse (in inglese)

Correlati

Query Tags: WP_Query (Classe), get_query_var(), query_posts(), have posts(), the_post(), rewind_posts(), wp_reset_postdata(), wp_reset_query()

See also index of Class Reference and index of Function Reference.