WP_Query: Como Usar + Exemplos com Códigos

Por padrão, o WordPress automaticamente classifica seus posts dos mais recentes para os mais antigos. Ainda que os visitantes possam buscar por publicações específicas utilizando categorias e tags, eles podem não conseguir encontrar o conteúdo que desejam. Para organizar seus posts e fazer uma curadoria para cada visitante, pode ser útil usar o WordPress WP_Query.

Usando o WP_Query, você pode personalizar a exibição dos posts e páginas do seu site. Essa classe PHP permite que você simplifique solicitações complexas ao banco de dados. Como desenvolvedor ou dono de sites, o WP_Query pode te ajudar a customizar suas páginas para além do seu tema padrão. 

Neste tutorial vamos explicar o que é WP_Query. Depois, vamos te mostrar como utilizar essa função no seu site WordPress. Por fim, oferecemos alguns exemplos de como implementar essas práticas em seu blog. Vamos lá!

Uma Introdução ao WP_Query

No WordPress, os dados do seu site são armazenados em um banco de dados MySQL. Esse banco de dados inclui tudo, desde posts, páginas e comentários, até as configurações do site. 

Quando um visitante clica em qualquer botão ou link do seu site, essa ação envia uma solicitação para o seu banco de dados WordPress.

Então, o seu banco de dados localiza e obtém a página ou post específico e exibe eles em seu site, baseado nessa solicitação — que é chamada de query. 

Como dono de um site, você pode tirar proveito das queries para buscar informações específicas no seu banco de dados. Apesar de ser possível construir queries SQL, esse não é o modo mais eficiente para obter informações. É aí que entra a WP_Query.

A WP_Query é uma classe PHP que pode ser utilizada na construção de queries para seu banco de dados. Essa classe já vem integrada no WordPress, e é acionada a cada vez que alguém busca por seus conteúdos.

De todo modo, implementar uma query WordPress personalizada pode permitir que os usuários encontrem algum conteúdo específico sem necessitar de uma pesquisa. Se você precisa renderizar um grupo específico de posts no front-end do seu site, é possível fazer isso facilmente utilizando um tipo de post personalizado WP_Query.

Por exemplo, você pode querer criar posts personalizados no WordPress. Para exibir esses posts, você pode escrever uma query específica. Abaixo indicamos a estrutura de código básica que pode ser utilizada para isso:

// WP QUERY

$query = new WP_Query([

'post_type' => 'press-release'

"posts_per_page => 25,

'category_name' => 'health',

]);

Esse código funciona ao personalizar o Loop. Basicamente, o Loop é um código PHP que o WordPress utiliza para exibir certas publicações. O WordPress sabe como processar e formatar cada post baseado em critérios específicos do seu tipo de post personalizado WP_Query.

A WP_Query também é muito útil para desenvolvedores. Você pode personalizar temas do WordPress utilizando esta classe PHP sem consultar diretamente o banco de dados.

Como Usar a WP_Query do WordPress (4 Métodos)

Agora que você já sabe o básico sobre o que é WP_Query, vamos discutir como criar sua primeira query. Desse modo, você poderá personalizar a exibição do seu site de forma simples e rápida!

1. Crie um Loop

Você precisará se familiarizar com o WordPress Loop para começar. Como mencionado anteriormente, o Loop é responsável por extrair os dados de um post a partir do banco de dados. Ele determina como seu conteúdo será exibido de acordo com os arquivos de template do seu tema. 

Baseado nos parâmetros que você definir, abaixo indicamos o que o Loop é capaz de exibir:

• Conteúdos de posts e campos personalizados do WordPress
• Títulos e trechos de posts na página inicial
• Conteúdo e comentários de um único post
• Conteúdo de página individual usando tags do template

Antes de personalizar o Loop com WP_Query, você precisará saber qual a estrutura do Loop. Aqui indicamos um exemplo de loop básico:

<?php

if ( have_posts() ) :

   while ( have_posts() ) : the_post();

      // Display post content

   endwhile;

endif;

?>

Vamos analisar individualmente cada parte deste loop. Primeiramente, a função “have_posts()” vai verificar se há posts em seu site. Caso sim, a condição “while” dará continuação ao loop para todos os posts. Basicamente, isso informa o seu banco de dados que todo post deve ser exibido em seu site. 

De todo modo, você pode querer não exibir todos os seus posts. Ao inserir o código WP_Query no Loop, você pode habilitar o WordPress para que ele renderize apenas certos posts:

?php

// The Query

$the_query = new WP_Query( $args );

// The Loop

if ( $the_query->have_posts() ) {

   echo '<ul>';

   while ( $the_query->have_posts() ) {

       $the_query->the_post();

       echo '<li>' . get_the_title() . '</li>';

   }

   echo '</ul>';

} else {

  // no posts found

}

/* Restore original Post Data */

wp_reset_postdata();

Esse código contém a mesma estrutura básica do Loop com os comandos if e while. Entretanto, há uma string adicional de WP_Query.

Você pode personalizar o Loop para que o seu site faça a exibição de posts específicos, como aqueles associados a certos autores, categorias e taxonomias do WordPress, tudo de acordo com os parâmetros que você configurar. Também é possível filtrar os resultados de acordo com a data, tag, campos personalizados e outras categorias. Ou seja, no geral, quando falamos em personalizar o Loop com WP_Query, há muitos caminhos que você pode seguir. 

2. Use Argumentos

Quando você estruturar sua codificação em WP_Query, será necessário incluir quatro elementos básicos:

• Argumentos da query
• A query em si 
• O loop
• Terminações para resetar os dados dos posts

Uma das partes mais fundamentais da sua query é o argumento (argument em inglês), geralmente nomeado de WP_Query args. O argumento informa ao WordPress quais dados você deseja obter a partir do banco de dados. Ao invés de exibir todo o conteúdo dos seus posts, o argumento irá determinar algumas condições no seu loop.

Você provavelmente reparou na linha ($args) no nosso exemplo anterior. Ali é onde você irá incluir seu query argument.

Para estruturar seus argumentos WP_Query, será necessário posicionar certos parâmetros em uma matriz (array). Vamos discutir os parâmetros de forma mais aprofundada na próxima seção, mas abaixo está a estrutura padrão de um argumento básico:

$args = array(

    'parameter1' => 'value',

    'parameter2' => 'value',

    'parameter3' => 'value'

);

Por exemplo, se você deseja exibir apenas posts que possuem a tag “cooking”, seu argumento pode ser estruturado como no código indicado abaixo:

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

Se você não incluir um WP_Query arg, nenhum conteúdo será obtido no seu banco de dados. Sem essa informação, o WordPress não sabe quais posts devem ser exibidos. 

3. Defina Parâmetros

Como mencionamos na seção anterior, configurar parâmetros é um passo importante para personalizar a WP_Query. Você pode habilitar o WordPress para que ele localize no banco de dados e faça a exibição de uma coleção de posts personalizada, basta especificar essa informação.

Se você não tem certeza quanto a quais parâmetros incluir em seu argumento, o WordPress oferece exemplos para diversos usos. Dado que esses exemplos já são codificados para você, eles podem poupar muito tempo e esforços quando estiver construindo sua classe WP_Query.

Abaixo listamos alguns parâmetros comuns que você pode utilizar:

• Posts_per_page – define o número de posts que você deseja exibir.
• Author – limita os resultados a partir de um ou mais autores.
• Cat – especifica as categorias que os resultados devem abranger.
• Tag – define posts que possuem etiquetas específicas. 
• Orderby – classifica os resultados por autor, tipo de post, data, etc.
• Order – ordena os resultados em ordem crescente ou decrescente. 
• Post_type – define se a query deve requisitar posts, páginas ou tipos de posts personalizados. 
• Post_status – especifica se os posts estão em progresso, agendados, publicados ou deletados. 

Por exemplo, você pode precisar exibir posts de uma certa categoria. Nesse caso, é possível incluir o nome e a slug de tal categoria:

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

O exemplo acima define a exibição de posts incluídos nessa categoria WP_Query e qualquer outra child-page da mesma categoria.

Usando parâmetros diferentes, você também pode exibir posts de uma data específica. Por exemplo, para exibir conteúdos de 9h até 17h em dias da semana, o parâmetro que pode ser utilizado é este indicado abaixo:

$args = array(

    'date_query' => array(

        array(

            'hour'  => 9,

            'compare'   => '>=',

        ),

        array(

            'hour'  => 17,

            'compare'   => '<=',

        ),

        array(

            'dayofweek' => array( 2, 6 ),

            'compare'   => 'BETWEEN',

        ),

    ),

    'posts_per_page' => -1,

);

$query = new WP_Query( $args );

O número de parâmetros que você pode utilizar é praticamente ilimitado. Ao incluir essas condições personalizadas em seus argumentos, sua WP_Query poderá apresentar os dados corretos com sucesso. 

4. Modifique as Propriedades da Classe com Métodos

Já que a WP_Query é uma classe PHP, ela contém constantes de classe, chamadas de propriedades. Essas funções são variáveis para o elemento PHP. 

Os desenvolvedores do WordPress recomendam não alterar as propriedades da classe WP_Query diretamente. De todo modo, você pode utilizar métodos para interagir com elas. 

Os methods funcionam de forma similar às funções. Quando você modifica os métodos de uma classe WP_Query, é possível personalizar os dados requisitados pela query ao banco de dados. 

Na documentação para WP_Query, há uma lista de diversas funções para tarefas básicas. Por exemplo, incluir uma função reset_postdata() pode ser um passo importante quando estiver escrevendo sua WP_Query. Esse método reseta as propriedades para $current_post e $post.

Aqui está um exemplo de como esse método se parece:

<?php

// the query

$the_query = new WP_Query( $args ); ?>

<?php if ( $the_query->have_posts() ) : ?>

   <!-- pagination here -->

   <!-- the loop -->

   <?php while ( $the_query->have_posts() ) : $the_query->the_post(); ?>

       <h2><?php the_title(); ?></h2>

   <?php endwhile; ?>

   <!-- end of the loop -->

   <!-- pagination here -->

   <?php wp_reset_postdata(); ?>

<?php else : ?>

   <p><?php _e( 'Sorry, no posts matched your criteria.' ); ?></p>

<?php endif; ?>

Em última instância, você deve adicionar este método caso utilize a função the_post() em sua query. Ela garante que as tags do template usem o post atual da query principal. 

Abaixo indicamos alguns métodos adicionais que podem ser usados para modificar as propriedades da sua WP_Query:

• get_posts – obtém um conjunto de posts de acordo com as variáveis definidas. 
• have_posts – determina se os posts estão disponíveis no Loop.
• generate_postdata – exibe os posts.
• fill_query_vars – completa as variáveis da query não estão listadas nos parâmetros. 

A partir das informações e configurações que você definir, é possível personalizar sua classe WP_Query para que ela execute a função necessária em seu site. Esta é uma maneira flexível e segura de modificar as propriedades da classe.

Exemplos de WP_Query

Assim que você aprender o básico do WordPress WP_Query, já pode começar a utilizar essa classe PHP para personalizar o design do seu site. Já que você pode definir vários parâmetros para isso, as opções de customização são quase infinitas. 

Vamos discutir alguns dos exemplos mais comuns do uso do WP_Query para você se inspirar!

1. Posts Mais Recentes de uma Determinada Categoria

Geralmente, os visitantes de sites estão mais interessados em conteúdos novos. Depois que eles lerem um de seus posts, é importante que sua página ofereça algum tipo de conteúdo relacionado. Ao recomendar seus posts mais recentes, você consegue direcionar os usuários para outros conteúdos que eles possam gostar. 

Há diferentes formas de aprender a adicionar posts relacionados no WordPress, e com essa WP_Query, isso pode ser especialmente útil para sites que possuem posts sensíveis aos fatores de horário e data. Por exemplo, um visitante pode ler um artigo científico sobre perda de memória. Utilizando a classe WP_Query, você pode destacar tópicos similares com pesquisas atualizadas: 

Se você deseja exibir os posts mais recentes de uma categoria específica, é possível utilizar essa codificação em WP_Query:

<?php

// Get the current post id.

$current_post_id = get_the_ID();

// Get the current post's category (first one if there's more than one).

$current_post_cats = get_the_category();

$current_post_first_cat_id = $current_post_cats[ 0 ]->term_id;

// Setup arguments.

$args = array(

  // Get category's posts.

   'cat' => $current_post_first_cat_id,

  // Exclude current post.

   'post__not_in' => array( $current_post_id )

);

// Instantiate new query instance.

$my_query = new WP_Query( $args );

?>

Depois de editar essa query com as informações de seu site (substituindo os respectivos dados), você pode exibir posts similares ao que o visitante acabou de ler. Esse processo é capaz de guiar o usuário até informações relevantes e atualizadas de forma eficiente, sem que ele precise pesquisar por elas. 

2. Posts Publicados esta Semana

Se você possui um público dedicado, os leitores vão querer ler seus novos artigos assim que eles forem publicados. Ao construir o design do seu site de forma que ele coloque os posts mais recentes em destaque, você consegue oferecer a melhor experiência para o usuário, exibindo as informações mais relevantes para ele.

Especialmente caso você tenha um site de notícias, será necessário ordenar seus posts de mais recentes para mais antigos. Ao fazer isso, você permite que os leitores encontrem conteúdos urgentes e relevantes de forma rápida e fácil. 

Usando a classe WP_Query, você pode definir parâmetros baseados na data da publicação. Por exemplo, Ao filtrar posts e exibir apenas aqueles publicados na última semana, você consegue evitar que os visitantes vejam artigos desatualizados:

<?php 

  $arguments = array(

     "date_query" => array(

        array(

          "year" => date( "Y" ),

          "week" => date( "W" ),

        )

     )

  );

  $posts = new WP_Query($arguments);

?>

Ao personalizar o parâmetro date_query, você é capaz de segmentar os posts publicados recentemente. Apesar de ser possível incluir seus próprios valores personalizados para definir a data limite, pode ser mais eficiente destacar os artigos escritos nos últimos sete dias. 

3. Posts Populares de Acordo com a Quantidade de Comentários

De forma similar à anterior, você pode promover os posts que o seu público mais gostou. Ao informar aos usuários que certas publicações receberam muito engajamento, você pode encorajá-los a clicar em tais posts para ver mais do conteúdo.

Já que o WordPress não monitora a quantidade de visualizações dos seus posts, você precisará adicionar essa funcionalidade manualmente. Isso pode ser feito com um plugin, mas esse recurso adicional também pode desacelerar seu site.

Com a WP_Query, você ainda pode sugerir aos leitores outros posts populares de acordo com o número de comentários deles. Essa é uma boa maneira de exibir os artigos do seu site que os leitores mais gostaram:

Abaixo indicamos o código que você pode usar para estruturar suas recomendações de posts baseadas em popularidade:

<?php

// Setup arguments.

$args = array(

  // Order by comment count.

   'orderby' => 'comment_count'

);

// Instantiate new query instance.

$my_query = new WP_Query( $args );

?>

Você também pode limitar ainda mais esses resultados a partir de uma certa categoria. Basta adicionar um parâmetro com o nome da categoria desejada:

<?php 

  $arguments = array(

     "category_name" => "fiction",

     "orderby" => "comment_count",

     "posts_per_page" => 5,

  );

  $posts = new WP_Query($arguments);

?>

Isso também vai limitar as recomendações em até cinco posts. Se necessário, você pode editar esse valor por um número diferente e assim exibir a quantidade de posts que desejar. 

4. Posts do Mesmo Autor e Categoria

Quando os visitantes leem um de seus blog posts, eles podem acabar gostando muito daquele conteúdo. Por exemplo, eles podem simplesmente preferir o estilo de escrita daquele autor ou o tópico do artigo em si.

Nesses casos, você pode utilizar a classe WP_Query para oferecer recomendações de posts similares. Dessa forma, os visitantes conseguem clicar em artigos adicionais para continuar a leitura:

Para criar uma seção de posts similares, você precisará implementar uma string WP_Query específica. Ela irá buscar por blog posts em seu site que possuam o mesmo autor ou autora e a mesma categoria. 

Aqui está o código que você pode utilizar:

<?php 

  $arguments = array(

     "author_name" => "john",

     "category_name" => "fiction",

     "posts_per_page" => 3,

  );

  $posts = new WP_Query($arguments);

?>

Quando estiver implementando esse código, você deverá substituir ‘john’ pelo nome do autor em questão. Do mesmo modo, delete a palavra ‘fiction’ e inclua o nome da categoria desejada. Por fim, sinta-se à vontade para modificar a quantidade de recomendações de posts exibida na página. 

5. Posts Anuais de um Autor ou Autora

Se você possui um blog mais popular, provavelmente há muitos autores diferentes escrevendo posts para ele. Depois de algum visitante ler um dos artigos de seu site, ele pode querer encontrar publicações adicionais daquele autor.

Nesse caso, você pode listar os posts escritos por um autor ou autora no último ano. Com esse método, você ainda pode dar aos visitantes mais informações sobre o autor e uma lista de suas publicações anteriores:

Para desenvolver uma lista com os posts anuais de um autor, é possível utilizar essa WP_Query:

<?php

// Get the year we're in.

$current_year = date( 'Y' );

// Setup arguments.

$args = array(

  // Get the author with the nicename "john".

   'author' => 'john',

  // Get his posts from this year.

   'year'   => $current_year

);

// Instantiate new query instance.

$my_query = new WP_Query( $args );

?>

Esses dados farão a solicitação ao banco de dados de todos os posts escritos por um autor ou autora específicos. Além disso, os resultados também serão refinados a partir do ano atual. Desse modo, nenhum artigo publicado há mais de um ano atrás será exibido na lista. 

6. Prévia de Posts Agendados

Para sua audiência dar uma espiadinha nos próximos conteúdos a serem lançados no blog, você pode listar seus posts agendados no site. Usando a classe PHP WP_Query, você pode exibir o título e trechos de seus futuros posts.  

Isso ajuda a gerar interesse em seus artigos antes deles serem lançados. Além do mais, é bastante simples implementar essa funcionalidade com WP_Query:

<?php

/*

* Usage with Excerpts:

*

* <?php echo tutsplus_show_drafts(); ?>

*

* Usage without Excerpts:

*

* <?php echo tutsplus_show_drafts( false ); ?>

*/

function tutsplus_show_drafts( $show_excerpts = true ) {

  // Setup arguments.

   $args = array(

       'post_status' => 'future',

       'nopaging' => true

   );

  // Instantiate new query instance.

   $my_query = new WP_Query( $args );

  // Check that we have query results.

   if ( $my_query->have_posts() ) {

      // Begin generating markup.

       $output = '<section class="pending-posts">';

      // Start looping over the query results.

       while ( $my_query->have_posts() ) {

           $my_query->the_post();

          // Output draft post title and excerpt (if enabled).

           $output .= '<div class="pending">';

               $output .= '<h3 class="pending-title">' . get_the_title() . '</h3>';

                   $output .= get_the_title();

               $output .= '</h3>';

               if ( $show_excerpts ) {

                   $output .= '<div class="pending-excerpt">';

                       $output .= get_the_excerpt();

                   $output .= '</div>';

               }

           $output .= '</div>';

       }

      // End generating markup.

       $output .= '</section>';

   } else {

      // Let user know that nothing was found.

       $output = '<section class="drafts-error">';

           $output .= '<p>' . __( 'Nothing found', 'tutsplus' ) . '</p>';

       $output .= '</section>';

   }

   wp_reset_postdata();

   return $output;

}

?>

Esse código irá automaticamente configurar uma visualização prévia de seus posts agendados com o título deles. Você também pode incluir um resumo ou trecho caso necessário. 

Conclusão

A WP_Query possibilita a realização de solicitações ao banco de dados WordPress de uma maneira simples. Utilizando essa classe PHP, você pode personalizar a exibição do seu site e oferecer uma experiência única para cada visitante online. 

Abaixo, relembramos as quatro formas com que você pode usar a WP_Query no WordPress:

• Crie um Loop.
• Use argumentos da query.
• Defina parâmetros específicos.
• Modifique as propriedades da classe.

Quando estiver familiarizado e já dominando essas técnicas de WordPress WP_Query, você poderá recomendar posts específicos baseados em popularidade, data, autor, categoria, e mais. 

Caso ainda tenha questões adicionais quanto à WP_Query, fique à vontade para deixar um comentário na seção abaixo. Lembre-se de utilizar uma hospedagem com WordPress confiável para que seu site tenha o melhor desempenho possível.