WP_Query ou get_posts(), qual usar para consultar posts no WordPress?

Criar sites dinâmicos no WordPress muitas vezes depende da sua capacidade de extrair conteúdo específico. Este guia é dedicado aos pedidos de posts – o método de extrair e exibir posts-alvo com base nos seus critérios. Vamos explorar dois métodos: WP_Query ou get_posts(), bem como suas funções e exemplos práticos.

Escolhendo entre WP_Query ou get_posts()

O WordPress oferece duas maneiras de solicitar posts: get_posts() e WP_Query. Ambos os métodos são eficazes, mas a escolha depende das suas preferências e de pequenos detalhes de desempenho.

• get_posts() retorna uma matriz de posts.
• WP_Query cria um objeto de consulta que oferece mais flexibilidade ao lidar com os resultados.

É importante notar que o uso de get_posts() pode afetar o ciclo global de consultas do WordPress se não for limpo corretamente.

A verdadeira magia reside nos argumentos que você fornece para get_posts() ou WP_Query. Esses argumentos definem os parâmetros de seleção de posts. Vamos explorar alguns argumentos comumente usados:

• post_type: Especifique o tipo de postagens que deseja obter, por exemplo, “post” (postagem), “page” (página) ou tipos de postagens personalizadas.
• posts_per_page: Defina o número de postagens exibidas por página. Use -1 para obter todas as postagens.
• category__in: Selecione postagens pertencentes a categorias específicas (lista de IDs de categorias separadas por vírgulas).
• post__not_in: Exclua postagens com IDs específicos dos resultados (matriz de IDs de postagens).
• orderby: Ordene as postagens por vários critérios, como “date” (data), “title” (título) ou campos personalizados.
• meta_query: Selecione postagens com base em metadados personalizados para filtragem avançada.

Para a maioria dos casos em que são necessários critérios simples de seleção de postagens, get_posts() é uma ótima escolha. Mas se você precisar de paginação, filtragem ou trabalho mais complexo com os resultados, WP_Query fornecerá a flexibilidade necessária.

Consulta global? Não se preocupe!

Em cada página do WordPress, por padrão, é executada uma consulta global. Por exemplo, ao visitar o arquivo de uma categoria, o WordPress automaticamente faz uma consulta para exibir as postagens correspondentes. Temas geralmente usam o loop (the loop) para acessar as postagens dessa consulta.

Criar uma nova consulta com seu próprio loop dentro do loop global requer cuidado para evitar conflitos. No entanto, se o seu objetivo for alterar a consulta global existente do WordPress, é uma história completamente diferente, que exploraremos em um artigo separado.

get_posts() – Simplicidade e velocidade

get_posts() é uma maneira conveniente de obter uma matriz de postagens com base nos seus critérios. É adequado para situações em que não há necessidade de filtragem ou paginação complexas.

Vantagens:

• Simplicidade: Fácil de usar e implementar no código do tema.
• Velocidade: Mais rápido que WP_Query, especialmente com um grande número de postagens.

Desvantagens:

• Flexibilidade limitada: Não é adequado para consultas complexas com paginação ou filtragem por campos de metadados.

$custom_query = get_posts(array(
// Seus argumentos de consulta
));
foreach ($custom_query as $custom_post) {
// Acesso às propriedades do post atual (não é possível usar funções de modelo como the_title() e assim por diante…)
}

Se for necessário usar funções de modelo, então você pode usar o seguinte código:

$custom_query = get_posts(array(
// Seus argumentos de consulta
));
foreach ($custom_query as $post) {
setup_postdata($post);
// agora as funções funcionarão
the_title();
}
wp_reset_postdata();

Funções auxiliares

setup_postdata($post) – Define o objeto de postagem global para usar funções de modelo dentro do loop foreach.
wp_reset_postdata() – Reseta o objeto de postagem global após o loop.

WP_Query – Flexibilidade e controle

WP_Query cria um objeto de consulta que oferece controle total sobre os resultados.

Vantagens:

Flexibilidade: Permite construir consultas complexas com filtragem por vários parâmetros (categorias, tags, campos personalizados) e implementar paginação. Controle sobre os resultados: Oferece mais opções para trabalhar com as postagens obtidas.

Desvantagens:

Complexidade: Requer um entendimento mais profundo da estrutura das consultas do WordPress. Desempenho: Pode ser um pouco mais lento que get_posts() com um grande número de postagens.

$custom_query = new WP_Query(array(
// Seus argumentos de consulta
));
if ($custom_query->have_posts()) {
while ($custom_query->have_posts()) : $custom_query->the_post();
// Acesso às propriedades do post atual
the_title();
endwhile;
wp_reset_postdata();
}

Argumentos de Consulta no WordPress (WP_Query)

Para controlar a seleção de postagens no WordPress, a classe WP_Query oferece uma variedade de parâmetros (argumentos). A lista completa de argumentos pode ser encontrada na documentação do WP_Query.

Exemplos de argumentos:

• Pesquisa por taxonomia (categorias, tags, etc.)
• Filtragem por metadados das postagens (campos adicionais)
• Seleção por tipo de postagem (páginas, postagens, produtos, etc.)
• Inclusão ou exclusão de postagens específicas
• Classificação dos resultados por vários critérios

Vamos examinar alguns exemplos comuns de uso de argumentos para seleção de postagens.
Exemplo 1: Postagens relacionadas da mesma categoria

Suponha que você queira exibir um bloco de “Postagens Relacionadas” no final de cada artigo. Ele deve mostrar uma seleção aleatória de 3 postagens da mesma categoria que o artigo atual, excluindo a própria postagem atual.

$post_id = get_the_ID(); // ID da postagem atual
$custom_query = new WP_Query([
'post_type' => 'post',
'posts_per_page' => 3,
'category__in' => wp_get_post_categories($post_id),
'post__not_in' => [$post_id],
'orderby' => 'rand'
]);

Vamos analisar os argumentos:

• post_type – especifica o tipo de postagem a ser selecionado (“post” – postagens regulares).
• posts_per_page – define o número de postagens por página (3).
• category__in – filtra postagens por categorias. Usamos wp_get_post_categories para obter uma matriz de IDs das categorias da postagem atual.
• post__not_in – exclui postagens específicas por ID (a postagem atual).
• orderby – define a ordem de classificação dos resultados (“rand” – ordem aleatória). A documentação sobre as opções de classificação está aqui: URL orderby query post wordpress.

Exemplo 2: Todas as postagens de um tipo personalizado com várias opções de classificação

Suponha que você tenha um tipo de postagem personalizado “book” (livros) e queira exibir todos os livros publicados em uma página de modelo. A ordenação deve ser feita primeiro pelo “menu_order” (ordem do menu, que pode ser definida para cada livro) e depois pelo título.

$custom_query = new WP_Query([
'post_type' => 'book',
'posts_per_page' => -1,
'orderby' => ['menu_order' => 'ASC', 'title' => 'DESC']
]);

Vamos analisar os argumentos:

• post_type – especifica o tipo de postagem (“book”).
• posts_per_page – o valor “-1” significa selecionar todas as postagens (publicadas, se não especificado de outra forma no argumento post_status).
• orderby – uma matriz para especificar os critérios de classificação. Primeiro, classifica por “menu_order” em ordem crescente (ASC), depois por título em ordem decrescente (DESC).

Exemplo 3: Postagens com metadados específicos

Suponha que você tenha um tipo de postagem personalizado “book” (livros) e deseja selecionar todos os livros que não estão publicados ou que foram publicados entre 2000 e 2022. O ano é armazenado como um campo de metadados separado para a postagem.

$custom_query = new WP_Query([
'post_type' => 'book',
'posts_per_page' => -1,
'meta_query' => [
'relation' => 'OR',
[
'key' => 'book_status',
'value' => 'unpublished',
'compare' => '='
],
[
'key' => 'year_published',
'value' => [2000, 2022],
'type' => 'numeric',
'compare' => 'BETWEEN'
]
]
]);

Vamos analisar os argumentos:

• meta_query – uma matriz para definir as condições com base nos metadados das postagens.
• relation – especifica o relacionamento entre as condições (“OR” – OU, “AND” – E).
• Arrays aninhados dentro de meta_query descrevem condições individuais:
  • key – a chave dos metadados (por exemplo, “book_status” ou “year_published”).
  • value – o valor dos metadados para comparar.
  • compare – o operador de comparação (por exemplo, “=”, “!=”, “<“, “>”, “BETWEEN”).
  • type – o tipo de dados dos metadados (por padrão, é uma string; para valores numéricos – “numeric”).

Conclusão. WP_Query ou get_posts?

Neste artigo, exploramos detalhadamente dois principais métodos de consulta de postagens no WordPress. Aprendemos como construir uma consulta e um loop e em quais casos usar cada abordagem:

get_posts() – um método simples e rápido, adequado para consultas simples sem filtragem ou paginação complicada. Ele retorna uma matriz de postagens.

WP_Query – um método mais flexível e poderoso que permite criar consultas complexas com filtragem por vários parâmetros e implementar paginação. WP_Query retorna um objeto de consulta que oferece controle total sobre os resultados.