O WordPress get_posts é uma função poderosa que permite aos desenvolvedores recuperar partes do conteúdo do banco de dados do WordPress. Você pode especificar com o maior detalhe quais posts, páginas e tipos de posts personalizados você está procurando, obter seu conjunto de resultados personalizado, então filtrar e ordenar os itens como um ninja PHP/MySQL.

Mas não se assuste se você não for um profissional de PHP, há inúmeros tutoriais PHP que você pode assistir ou ler e aprender a linguagem. Você só precisa de um pouco de conhecimento de PHP para criar listas personalizadas de posts para exibir em seu site, já que a função get_posts mantém um array de parâmetros que permitem construir consultas simples ou avançadas.

A utilização do WordPress get_posts é um processo em duas etapas:

  • Primeiro, você tem que construir sua consulta personalizada. Na verdade, ele não vai parecer uma consulta MySQL, e você não vai escrever nenhuma instrução SELECT. Você só precisa definir um array de parâmetros e passá-lo para a função get_posts. O WordPress converte esse array em uma consulta MySQL real e segura, executa-o contra o banco de dados e retorna um array de posts.
  • Segundo, você tem que atravessar o conjunto de resultados retornados por get_posts com um ciclo foreach.

Dito isto, neste post, vamos primeiro mergulhar nos conceitos chave mencionados acima, especificamente como funciona o get_posts, como construir uma consulta personalizada, e como mostrar os dados no front site.
Então, vou fornecer um exemplo do mundo real com um trecho de código que você pode pegar, editar e usar em seu ambiente de teste e desenvolvimento.

Nota: Nós geralmente diferenciamos entre postagens, páginas e tipos de postagens personalizados. Neste artigo, usamos o termo ‘posts’ para posts de blogs regulares, bem como para páginas e tipos de posts personalizados. Todos esses tipos de lançamento são gravados na tabela ‘wp_posts’ do banco de dados. A principal diferença entre os tipos de lançamento está no valor do campo ‘post_type’. Do ponto de vista de um desenvolvedor, publicações, páginas e tipos de publicações personalizados são todas publicações.

Introdução à Função get_posts do WordPress

O Codex descreve a função get_posts da seguinte forma:

Recupera um array das últimas mensagens, ou mensagens que correspondam aos critérios dados.

Podemos usar get_posts desta forma:

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

A função acima recupera os últimos 20 posts do blog na categoria especificada (por padrão o 'post_type' é 'post') e retorna um array de $post objects. Você pode iterar sobre a matriz para exibir as mensagens na tela. É muito fácil, certo?

get_posts usa WP_Query para recuperar itens do post, e mantém um array dos mesmos parâmetros disponíveis no WP_Query (com poucas exceções). Por isso temos uma enorme lista de variáveis que podemos usar para construir as nossas consultas personalizadas. Estes parâmetros estão agrupados nas seguintes 15 categorias:

  • Author Parameters
  • Category Parameters
  • Tag Parameters
  • Taxonomy Parameters
  • Search Parameters
  • Post & Page Parameters
  • Password Parameters
  • Post Type Parameters
  • Order & Orderby Parameters
  • Date Parameters
  • Custom Field (post meta) Parameters
  • Permission Parameters
  • Mime Type Parameters
  • Caching Parameters
  • Return Fields Parameter

Uma rápida olhada na lista acima pode lhe dar uma idéia da variedade de consultas personalizadas que você pode criar e executar no banco de dados do WordPress. Então, vamos mergulhar mais fundo nos parâmetros de consulta e começar a construir nossas listas de posts.

Como Criar Consultas com o WordPress get_posts

Cada categoria de parâmetros está relacionada com a mesma informação. Por exemplo, podemos criar uma consulta para recuperar mensagens do(s) autor(es) especificado(s) ou excluindo o(s) autor(es) especificado(s), definindo o autor por ID ou nicename. Da mesma forma, podemos construir consultas para buscar posts por categoria, tag, taxonomia, data, campos personalizados e muito mais.

Como Usar Parâmetros para Construir Consultas Simples

Muitos parâmetros podem ser utilizados de forma bastante semelhante, independentemente da categoria a que pertencem. Por exemplo, os seguintes parâmetros permitem consultar o banco de dados por autor(es) postado(s):

  • author (int) – ID do autor
  • author_name (string) – user_nicename do autor
  • author__in (array) – um array de IDs de múltiplos autores
  • author__not_in (array) – um array de IDs de múltiplos autores a serem excluídos do conjunto de resultados

Como podemos usar estes parâmetros?

No seguinte exemplo, o parâmetro 'autor' especifica que queremos os posts mais recentes do blog escritos pelo autor com ID = 1:

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

O mesmo parâmetro ‘autor’ permite consultar a base de dados de diferentes formas:

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

Assim, dependendo do valor do parâmetro, você terá um conjunto de resultados com posts de um único autor (inteiro), de vários autores (uma lista de valores separados por vírgulas) ou excluindo um autor (valores negativos).

Outros parâmetros proporcionam flexibilidade adicional. Por exemplo, a seguinte chamada para get_posts retorna um array dos últimos posts do blog de vários autores:

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

E também podemos excluir vários autores:

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

Da mesma forma, podemos usar parâmetros de categoria, parâmetros de tag, parâmetros de post type, com algumas diferenças específicas. Veja, como exemplo, os parâmetros de categoria:

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

De qualquer forma, nem todos os parâmetros são tão fáceis de usar como estes parâmetros. Além disso, podemos usar parâmetros de categoria, params de tipo post, params de tipo mime, etc. tudo em uma única consulta. Isso significa que temos controle granular sobre os itens no conjunto de resultados, e podemos construir consultas mais avançadas com base em tipos de posts, taxonomias personalizadas e campos personalizados.

Então, vamos mergulhar mais fundo!

Como Criar Consultas Avançadas no WordPress

Vamos dar um passo à frente com uma consulta mais avançada baseada em tipos de posts personalizados e taxonomias personalizadas. Digamos que tem o seguinte tipo de mensagem:

nome: livro
nome da taxonomia: book_category, book_author
suporte para: título, editor, miniaturas, excerto, campos personalizados

Tipos de Postos Personalizados e Taxonomias Personalizadas

Suponha que você queira uma lista dos livros mais recentes na taxonomia personalizada de book_category especificada. Aqui está a matriz de argumentos:

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

Os argumentos acima simplesmente dizem ao WordPress para recuperar todos os livros em 'sci-fi' 'book_category'.

O parâmetro 'tax_query' pega um array de arrays de argumentos (ou seja, um array de arrays). Esses arrays aninhados permitem construir consultas muito complexas baseadas em múltiplas taxonomias, como mostrado no exemplo abaixo:

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

Estes parâmetros permitem-nos recuperar uma lista dos últimos 10 tipos de post 'book' no 'sci-fi' 'book_category', escrito pelo 'book_author' com o ID #22. O parâmetro 'relation' define a relação lógica entre cada taxonomia listada em 'tax_query'. Acima definimos seu valor para AND porque precisamos recuperar todos os livros pertencentes à categoria 'sci-fi' AND escritos pelo autor #22.

Como Construir Meta Consultas Usando Parâmetros de Campo Personalizados

Ocasionalmente, você pode precisar criar listas de mensagens com base em uma chave de campo e/ou valor personalizado específico.

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

Estes parâmetros nos permitem recuperar todos os posts por chave de campo personalizada e valor. 'meta_compare' define o operador necessário para testar o valor do parâmetro 'meta_value'. Aqui 'meta_value' é '=', que também é o valor padrão.

Os valores disponíveis são '=', '!=', '>', '>=', '<', '<=', 'LIKE', 'NOT LIKE', 'IN', 'NOT IN', 'BETWEEN', 'NOT BETWEEN', 'NOT EXISTS', 'REGEXP', 'NOT REGEXP' ou 'RLIKE'.

Este é um exemplo muito fácil, mas podemos construir consultas mais avançadas. No exemplo seguinte, consultamos a base de dados de livros de fantasia publicados apó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'
		)
	)
);

E podemos ir ainda mais longe. No próximo exemplo estamos misturando um tipo de postagem com uma taxonomia personalizada e dois campos personalizados:

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

Aqui nós definimos um array de parâmetros para recuperar uma lista de livros de fantasia publicados após 2010 que custam BETWEEN $10 e $25.

Você pode ver que o parâmetro 'meta_query' funciona muito como o parâmetro 'tax_query'. Ele mantém uma matriz de arrays, permitindo-nos comprar consultas avançadas baseadas em múltiplos pares de meta-chave/valor. Para obter uma lista abrangente de parâmetros de consulta e um bom número de exemplos, consultar a documentação WP_Query.

Por que get_posts está Limitado a 5 Posts WordPress?

A função get_posts em os mesmos argumentos que WP_Query::parse_query() (veja o Codex), mas alguns parâmetros específicos fazem com que ele funcione um pouco diferente de um objeto WP_Query.

Talvez você não tenha usado o parâmetro 'numberposts' em suas consultas e você está querendo saber por que você vê apenas 5 itens em sua lista.

Por padrão, o número de lançamentos definidos em Configurações → Página de administração de leitura determina o número de lançamentos a serem recuperados por uma consulta do WordPress. De qualquer forma, se você não especificar um valor personalizado para 'numberposts' ou 'posts_per_page', get_posts retorna um número diferente de posts.

  • 'numberposts' é o número total de mensagens a recuperar. É um alias de 'posts_per_page' em WP_Query, mas há uma diferença entre os dois: por padrão, o número de posts a recuperar ao usar get_posts é 5, enquanto 'posts_per_page' em WP_Query padrão para o número de posts por página de seu blog WordPress. Você pode substituir o valor padrão definindo um valor personalizado para 'numberposts' ou 'posts_per_page' no array de argumentos.

Além de 'numberposts', os seguintes parâmetros são específicos de get_posts:

  • 'category' é uma lista separada por vírgulas de IDs de categoria. É um alias do parâmetro 'cat' em WP_Query.
  • O 'include' é uma lista de IDs postais separados por vírgulas. Este é um alias do parâmetro 'post__in' em WP_Query.
  • 'exclude' é uma lista separada por vírgulas de IDs postais.
  • 'suppress_filters' especifica se os filtros devem ser suprimidos. Esse parâmetro padrão é true em get_posts, enquanto que o padrão é false em WP_Query (veja em Track).

A função get_posts é definida em wp-includes/post.php. Você pode mergulhar profundamente em como get_posts funciona verificando o código fonte no Track (WordPress 5.2) ou em sua instalação WordPress local.

Encomenda de Itens

'orderby' e 'order' ordenar os itens no conjunto de resultados. Você classifica os posts por 'ID', 'author', 'title', 'name', 'type', 'date', 'modified', 'parent', 'rand', 'comment_count' e de muitas outras maneiras, em ordem ascendente ou descendente.

Se você tem uma consulta simples, você só precisa definir um valor para 'order' e 'orderby'. No exemplo a seguir, os posts são ordenados pelo nome do post em ordem crescente:

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

Isso é muito simples. Mas e se tivesses uma consulta avançada? Ou seja: Podemos classificar itens por um ou mais valores de campo personalizados em uma meta consulta avançada?

O WordPress 4.0 e o WordPress 4.2 trouxeram melhorias importantes aos parâmetros 'orderby' e 'meta_query'. Agora temos uma nova sintaxe para ordenação por cláusulas específicas de uma meta query. Graças à nova sintaxe, podemos usar índices para criar referências às cláusulas específicas da meta query a partir do parâmetro 'orderby'.

Graças a estas melhorias, a meta query no exemplo acima pode ser escrita da seguinte forma:

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

No exemplo acima, ordenamos os elementos por 'price_clause'.

E podemos fazer ainda mais. A partir do WordPress 4.0, podemos passar para get_posts um array de índices de meta query ao invés de um único índice, como visto no exemplo abaixo:

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

Parabéns, você construiu uma meta query avançada e ordenou os resultados primeiro por 'price_clause' em ordem ascendente, depois por 'year_clause' em ordem descendente.

Veja a lista completa de opções de classificação no Codex.

Está na hora de mostrarmos os dados na primeira página.

Sugestão de leitura: Como Criar e Usar Facilmente uma Página phpinfo.

Como Exibir get_posts Retorno de Dados

WordPress get_posts retorna um array de objetos WP_Post dando-nos acesso a um número de variáveis para cada post selecionado armazenado na tabela de banco de dados 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
Estrutura da tabela wp_posts no phpMyAdmin
Estrutura da tabela wp_posts no phpMyAdmin

Você pode acessar facilmente esses dados com um ciclo foreach como o seguinte:

$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 encontrar pelo menos um post, ele retorna um array de itens que podemos atravessar para mostrar o título do post e um link para o post original. Usamos a função get_permalink para recuperar o post permalink, pois não temos uma variável WP_Post correspondente.

Isso é muito fácil, mas como podemos implementar esse código e construir nossas listas personalizadas de posts usando o WordPress get_posts?

Você pode mostrar listas de posts em suas páginas de várias maneiras.

Exemplo do Mundo Real: Como Exibir uma Lista Personalizada de Itens com um Código de Acesso

Vou mostrar-lhe como criar um atalho rápido e fácil que pode incluir no seu conteúdo. De qualquer forma, eu não vou mergulhar fundo em atalhos, como já abordamos esse tópico em um post anterior do blog.

Primeiro, crie um novo diretório na pasta wp-content/plugins da sua instalação local do WordPress ou em um ambiente de testes. Neste exemplo, eu nomeei o diretório kinsta-shortcodes.

Em wp-content/plugins/kinsta-shortcodes/crie um arquivo .php com o mesmo nome do novo diretório: kinsta-shortcodes.php.

Abra o novo ficheiro no seu editor de texto favorito e inclua o seguinte cabeçalho:

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

Agora temos um plugin novinho em folha, mas continua a não fazer nada. Navegue até a tela de administração de plugins no seu painel do WordPress e ative o novo plugin, certificando-se de que você tem o WP_DEBUG definido como true no seu arquivo wp-config.php.

A tua caixa de areia está agora pronta para os teus hacks. O próximo passo é registrar um gancho para um atalho personalizado:

/**
 * 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 é o nome do shortcode e kinsta_get_posts_cb é o retorno de chamada definido abaixo:

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

Definimos seis atributos de atalho que usamos para definir um array de parâmetros, que é finalmente passado para a função WordPress get_posts. Se $custom_posts não estiver vazio, então um ciclo foreach gera o HTML de uma lista desordenada de itens.

Agora você e os autores do seu blog podem incluir listas de posts usando um shortcode como o seguinte:

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

Naturalmente, você pode mudar a matriz de argumentos como você gosta e executar seus testes em qualquer post ou página do seu site de teste.

Uma lista avançada de posts construídos com a função get_posts
Uma lista avançada de posts construídos com a função get_posts

Resumo

O WordPress get_posts é uma função poderosa que permite que os desenvolvedores incluam listas de posts em qualquer lugar no frontend do seu site do WordPress. Ele usa WP_Query, mas é mais fácil de usar e é preferível a WP_Query quando você só precisa de listas de posts. De qualquer forma, uma referência direta a WP_Query é recomendada quando você precisa exibir posts em um Loop.

Então, construa suas listas, teste seu código, e quando tiver certeza de que ele funciona bem, então (e só então) empurre-o para o seu website ao vivo (mas execute um backup primeiro).

Agora gostaríamos de ter notícias suas. Qual é a sua experiência com o WordPress get_posts function? Você tem algum caso de uso para compartilhar conosco? Faça isso nos comentários abaixo!

Carlo Daniele Kinsta

Carlo é um apaixonado por webdesign e desenvolvimento frontend. Ele tem mais de 10 anos de experiência com WordPress e colaborou com diversas universidades e instituições educacionais na Itália e na Europa. Carlo já publicou inúmeros artigos e guias sobre WordPress, tanto em sites italianos quanto internacionais, além de revistas impressas. Você pode seguir ele no LinkedIn e no X.