Conhecendo a Classe WP_QUERY

Conhecendo a Classe WP_QUERY

Como aprendemos em conteúdos anteriores, o WordPress trabalha com um tipo de loop principal que é usado para carregar as informações referentes a cada página ou postagem.

O primeiro deles, refere-se ao loop padrão que aprendemos em lições passadas, onde fazemos o uso do comando while() em conjunto com a função have_posts():

<?php while(have_posts()): the_post(); ?>

<!-- Aqui tratamos as informações do loop -->

<?php endwhile; ?>

Quando abrimos o conteúdo de uma página, o loop é responsável por carregar os conteúdos referentes a aquela página.

Quando abrimos o conteúdo de uma postagem, o loop é responsável por carregar os conteúdos referentes a aquela postagem.

E assim segue a lógica de carregamento de informações do WordPress.

Em lições passadas, nós aprendemos também, que podemos fazer o uso de Tags Condicionais em conjunto com as Template Tags para extrair dados relacionados com o conteúdo que está sendo carregado no loop.

Pois bem, no mundo do WordPress, existe um segundo loop um pouco mais avançado, que nos permite extrair dados de uma página ou postagem diretamente do banco de dados, como se fosse uma consulta SQL.

Esse segundo loop tem um nome, e é conhecido como WP_Query 🤖

O que é WP_Query?

WP_Query é uma classe do WordPress que é usada para recuperar postagens ou páginas do banco de dados com base em vários parâmetros de consulta.

Ela é bastante utilizada quando você precisa personalizar a exibição de conteúdo no seu tema.

É importante ressaltar que esta classe possui inúmeros argumentos, de modo que passaríamos horas e horas explicando para você cada um deles, de tão rico que essa classe é.

Portanto, o objetivo desta lição é fazer uma introdução básica da classe WP_Query() e como ela pode te ajudar 😉

Pois bem, tudo começa com a inicialização da classe, e isso pode ser feito em um dos seus arquivos de modelos de tema da seguinte forma:

$args = array(
 'post_type' => 'post',
 'category_name' => 'noticias',
 'posts_per_page' => 5
);

$query = new WP_Query($args);

Observação: O código acima não deve ser inserido dentro do loop padrão do WordPress.

Tudo começa quando instânciamos a classe WP_Query dentro de uma variável chamada $query, onde passando alguns argumentos para dentro da classe ($args).

Para quesito de exemplo, usamos ali alguns dos milhares de parâmetros que são aceitos pela classe:

post_type: Especifica o tipo de postagem a ser consultada (por exemplo, 'post', 'page', 'custom_post_type').

category_name,: Especifica o identificador da categoria. Podemos pesquisar também por tag, cat, tag_id.

posts_per_page: Define o número de postagens a serem exibidas por página.

orderby e order: Podemos passar um parâmetro que define a ordenação das postagens (por data, título, etc.).

meta_query: Permite a filtragem com base em valores de metadados personalizados.

Lembra que no início desta lição eu disse que a classe WP_Query se parece muito com uma consulta SQL? Então, tudo o que fizemos foi dizer para o WordPress:

"Hey WordPress, Retorne para mim 5 postagens por página, onde o tipo de post seja uma postagem, e que esses posts façam parte da categoria chamada noticias".

Vejamos abaixo, uma consulta com todos os argumentos mencionados acima:

$args = array(
 'post_type' => 'post', // Tipo de postagem (pode ser 'page', 'custom_post_type', etc.)
 'category_name' => 'noticias', // Nome da categoria a ser filtrada
 'posts_per_page' => 5, // Número de postagens por página
 'orderby' => 'date', // Ordenar por data
 'order' => 'DESC', // Ordem descendente (ou ASC para ascendente)
 'meta_query' => array(
 // Aqui você pode adicionar consultas para metadados personalizados, se necessário
 )
);

$query = new WP_Query($args);

Após isso, precisamos adicionar o resultado dessa pesquisa dentro do loop padrão do Wordpress, da seguinte forma:

if ($query->have_posts()) {
 while ($query->have_posts()) {
 $query->the_post();
 // Exibir o conteúdo da postagem aqui
 }
}

Perceba que estamos usando uma função existente na variável $query, para retornar o conteúdos dos posts, legal não acha?

Já no local onde está escrito o comentário //Exibir o conteúdo da postagem aqui, acredito que você já sabe muito bem o que fazer 😉

Por fim, logo após o final do while ou endwhile, você deve usar o comando wp_reset_postdata() garantindo que a consulta do WP_Query não afete a consulta principal do próprio WordPress, isto é, caso tenhamos que usa-la novamente na mesma página, por exemplo:

if ($query->have_posts()) {
 while ($query->have_posts()) {
 $query->the_post();
 // Exibir o conteúdo da postagem aqui
 }
 wp_reset_postdata();
}

Outros argumentos do WP_Query

Existe um grande número de argumentos suportados pela classe WP_Query, onde a cada nova atualização, novos argumentos são adicionados pela equipe de desenvolvimento.

Para consultar a lista completa de argumentos, basta acessar este link.

Argumentos Gerais:

post_type: Tipo de postagem a ser consultada.

post_status: Status da postagem a ser consultada (o padrão é 'publish' que significa publicado).

posts_per_page: Número de postagens a serem exibidas por página.

offset: Número de postagens a serem ignoradas no início da consulta.

orderby: Campo pelo qual as postagens devem ser ordenadas.

order: Ordem de classificação ('ASC' para ascendente, 'DESC' para descendente).

ignore_sticky_posts: Informamos um valor booleano para ignorar ou não posts em destaque.

Argumentos de Categoria e Taxonomia:

category_name: Nome da categoria a ser consultada.

cat: ID da categoria a ser consultada.

tag: Nome da tag a ser consultada.

tag_id: ID da tag a ser consultada.

tax_query: Array de argumentos para consultas de taxonomia personalizadas.

category__in: IDs das categorias a serem consultadas. Aqui passamos um array contendo números inteiros.

category__not_in: IDs das categorias que não serão consultadas. Aqui passamos um array contendo números inteiros.  

Argumentos de Data:

year, monthnum, day: Consultas por ano, mês ou dia específico.

date_query: Array de argumentos para consultas de data personalizadas.

Argumentos de Autor:

author: ID do autor a ser consultado.

author_name: Nome do autor a ser consultado.

author__in, author__not_in: Arrays de autores a serem incluídos ou excluídos.

Argumentos de Metadados:

meta_key, meta_value: Consultas por chave e valor de metadados.

meta_query: Array de argumentos para consultas de metadados personalizados.

Argumentos de Pesquisa:

s: Termo de pesquisa.

exact, sentence, search_terms, search_order, search_columns: Argumentos para refinar consultas de pesquisa.

Devemos usar ainda a query_posts()?

Antes da chegada da classe WP_Query(), usávamos a função query_posts() para retornar o conteúdo dos nossos posts.

Com o passar do tempo a função query_posts() foi caindo em desuso, e de acordo com a documentação do Wordpress: "todo tema moderno deve usar métodos mais confiáveis e atuais", sendo assim, melhor usarmos a WP_Query() mesmo.

Antes que nosso tema pare de funcionar por depreciação da função query_posts().

Conclusão

Nesta lição você aprendeu a criar um loop avançado por meio da função WP_Query().

Até a próxima lição 🥰