Guia: Modificar a consulta global do WordPress

Em alguns casos, pode ser necessário modificar a consulta global de postagem que o WordPress está realizando em qualquer página que você estiver visitando – tanto admin quanto frontend. Neste guia, veremos qual gancho usar e como alterar os argumentos da consulta ao seu gosto.

Qual gancho usar

Primeiro você precisa saber em qual gancho adicionar seu código. Precisamos de um gancho que aconteça logo após o WordPress configurar todos os argumentos, mas antes que a consulta real seja executada. Para isso usamos a ação pre_get_posts.

Neste gancho você obtém um parâmetro; que é um WP_Queryobjeto com o qual o WordPress executará a consulta posteriormente. Você faz alterações no objeto – mas não precisa devolvê-lo, pois o WordPress executará a consulta com o objeto modificado.

add_action('pre_get_posts', function($query) {
    // Add your code here
});

Modificar a consulta provavelmente requer que você use algumas tags condicionais para especificar os casos em que deseja alterá-la. Por exemplo, você pode querer segmentar a consulta apenas em resultados de pesquisa ou exibições de categoria.

Tags condicionais

O WordPress tem várias tags condicionais que você pode usar para especificar em quais casos deseja adicionar seu código. Uma tag condicional é simplesmente uma função que retorna true ou false dependendo do estado em que o WordPress está. Exemplos de tags condicionais comuns são is_admin()para verificar se estamos atualmente em admin ou frontend, is_singular()se estamos em um único post ou página no frontend e is_search()se estivermos na página de resultados da pesquisa.

Tenha em mente que o hook pre_get_postsé executado tanto para admin quanto para frontend. Se você deseja apenas afetar a consulta global no frontend, você precisa envolver seu código dentro de um if-check na tag condicional is_admin().

Observação sobre tags condicionais empre_get_posts

As tags condicionais são ótimas e tudo, mas há algumas coisas a serem lembradas ao usá-las dentro pre_get_postsde .

Em primeiro lugar, você precisa se familiarizar com a tag is_main_query(). Na verdade, a ação pre_get_postsé executada várias vezes para cada carregamento de página. Por exemplo pre_get_posts, é executado ao gerar cada menu (incluindo aqueles em widgets). Para modificar a consulta global real, por exemplo, postagens para um arquivo de categoria ou resultados de pesquisa, você precisa segmentar a "consulta principal" usando is_main_query().

Em segundo lugar, você precisa estar ciente dos casos em que precisa verificar as tags condicionais no objeto fornecido em vez de chamar a função “independentemente". Normalmente, quando você usa tags condicionais, você escreveria assim:

if (is_main_query()) {
    // Do stuff
}

No entanto, ao usar pre_get_posts, existem algumas tags condicionais que você precisa aplicar no objeto. Por exemplo:

Você deve sempre verificar is_main_query()o objeto fornecido em pre_get_posts. Leia a documentação de pre_get_posts para obter mais informações.

Este é um exemplo de verificação se não estamos no admin e se estamos na consulta do post principal:

Alterar ou adicionar argumentos

Como estamos trabalhando com um WP_Queryobjeto, você pode consultar a documentação do WP_Query para saber como construir seus argumentos para personalizar a consulta de posts. Lembre-se de que os argumentos já estão preenchidos. Nesse caso, você precisa anexar ou alterar os valores existentes. Ou remova os que você deseja remover.

Você usa a set()função no WP_Queryobjeto para definir argumentos. O método aceita dois argumentos, a chave do argumento e, em segundo lugar, o valor. Por exemplo, definir o posts_per_pageargumento seria feito assim:

Nos casos em que você deseja anexar ou alterar um argumento preexistente, normalmente faria isso salvando primeiro o argumento existente em uma variável. Você pode usar o método get()para isso. Em seguida, você modifica a variável, anexando ou mesclando matrizes ou outros enfeites. E, finalmente, você usa set()para substituir a variável modificada de volta no objeto de consulta. Eu recomendo usar var_dump()no objeto para ver o que ele contém, e essa também é uma boa maneira de verificar se suas tags condicionais estão corretas.

Aqui está um exemplo rápido de uso get()(simplesmente verificando se está vazio) e, se estiver, adicione seus próprios argumentos com set().

Observação sobre tax_query

O WordPress tem subclasses separadas para lidar com a WP_Tax_Queryparte taxonomia () dentro do WP_Query. Se você precisar fazer modificações de consulta de taxonomia mais complexas, a pre_get_postsação pode ser muito precoce. Alguns valores podem estar vazios porque são preenchidos posteriormente. Nesse caso, talvez seja melhor usar a ação parse_tax_queryem vez de pre_get_posts. Leia a documentação para este gancho para ver se isso é para você.

Conclusão

Os argumentos que você adiciona ou altera dependem inteiramente do que você deseja fazer, mas agora você deve ter algumas ideias sobre estratégias para obter a consulta global. Se você precisar obter algumas informações sobre o WP_Queryobjeto e como usar seus argumentos, meu post sobre como consultar postagens pode ser interessante.