Argumentos WP_Query: Taxonomias

Até agora nesta série, você aprendeu como WP_Query está estruturado e quais são suas propriedades e métodos. Agora estamos vendo os vários argumentos que você pode usar com WP_Query e como você os codifica.

WP_Query tem um grande número de argumentos possíveis, o que o torna extremamente flexível. Como você pode usá-lo para consultar praticamente qualquer coisa mantida em seu wp_posts table, ele tem argumentos para cada permutação de consulta que você deseja executar em seu conteúdo.

Neste tutorial, examinarei os argumentos para consultar termos de taxonomia.

Uma recapitulação sobre como os argumentos funcionam em WP_Query

Antes de começarmos, vamos recapitular rapidamente como os argumentos funcionam em WP_Query. quando você codificar WP_Query em seus temas ou plugins, você precisa incluir quatro elementos principais:

• os argumentos para a consulta, usando parâmetros que serão abordados neste tutorial
• a própria consulta
• o laço
• finalizando: fechando if e while tags e redefinindo dados de postagem

Na prática, isso será algo como o seguinte:

have_posts() ) {

    // Start looping over the query results.
    while ( $query->have_posts() ) {

        $query->the_post();

        // Contents of the queried post results go here.

    }

}

// Restore original post data.
wp_reset_postdata();

?>

Os argumentos são o que diz ao WordPress quais dados devem ser buscados no banco de dados e são esses que abordarei aqui. Então, tudo o que estamos focando aqui é a primeira parte do código:

$args = array(
    // Arguments for your query.
);

Como você pode ver, os argumentos estão contidos em uma matriz. Você aprenderá a codificá-los enquanto trabalha neste tutorial.

Codificando seus argumentos

Existe uma maneira específica de codificar os argumentos na matriz, que é a seguinte:

$args = array(
    'parameter1' => 'value',
    'parameter2' => 'value',
    'parameter3' => 'value'
);

Você deve colocar os parâmetros e seus valores entre aspas simples, use => entre eles e separe-os com uma vírgula. Se você errar, o WordPress pode não adicionar todos os seus argumentos à consulta ou você pode obter uma tela branca.

Os Parâmetros de Taxonomia

Definir parâmetros para termos de taxonomia é um pouco mais complicado do que para categorias e tags, pois você usa tax_query. Dentro desse argumento, você escreve uma matriz aninhada de argumentos para especificar a taxonomia e o termo usando estes parâmetros:

• taxonomy (corda): taxonomia
• field (corda): selecione o termo de taxonomia por ('term_id (predefinição), 'name' ou 'slug')
• terms (int/string/array): termo(s) de taxonomia
• include_children (boleano): Wincluir ou não filhos para taxonomias hierárquicas. O padrão é verdadeiro.
• operator (corda): operador para testar. Os valores possíveis são 'IN' (predefinição), 'NOT IN', 'AND', 'EXISTS' e 'NOT EXISTS'.

O fato de você ter o operator parâmetro significa que você não precisa escolher entre uma variedade de argumentos disponíveis para definir se está incluindo ou excluindo termos (como você faz para tags e categorias), mas use tax_query para tudo relacionado à taxonomia.

Se você deseja consultar várias taxonomias, também pode usar o relation parâmetro antes de todas as suas matrizes (uma para cada taxonomia) com AND ou OR para especificar se você deseja encontrar postagens com todos os termos ou com qualquer um deles.

Isso é mais facilmente explicado com alguns exemplos.

Consulta de um termo de taxonomia

Este é o cenário mais simples e envolve apenas o uso de uma matriz aninhada:

$args = array(
    'tax_query' => array(
        array(
            'taxonomy' => 'category',
            'field' => 'slug',
            'terms' => 'tutorial',
        )
    )
);

As consultas acima para postagens com o tutorial termo no category taxonomia. Observe que você também precisa usar o field parâmetro para identificar qual campo você está usando para identificar o termo, a menos que esteja usando o ID do termo, que é o padrão. Se você quisesse usar o termo ID, usaria algo assim:

$args = array(
    'tax_query' => array(
        array(
            'taxonomy' => 'category',
            'terms' => '11'
        )
    )
);

O uso do ID dificulta a identificação do que sua consulta está procurando posteriormente, mas evita possíveis problemas se você achar que seus usuários podem editar o termo slugs.

Consultando vários termos em uma taxonomia

Se você deseja identificar postagens com um ou mais de uma matriz de termos na mesma taxonomia, ainda escreve uma matriz aninhada, mas adiciona uma matriz de termos.

Por exemplo, para consultar postagens com algum de uma lista de IDs de termos de sua taxonomia, você usa:

$args = array(
    'tax_query' => array(
        array(
            'taxonomy' => 'post_tag',
            'terms' => [14, 17]
        )
    )
);

Mas e se você quiser consultar postagens com tudo desses termos? Você precisará usar o operator parâmetro dentro de sua matriz aninhada:

$args = array(
    'tax_query' => array(
        array(
            'taxonomy' => 'post_tag',
            'terms' => [14, 17],
            'operator' => 'AND'
        )
    )
);

Observe que o primeiro exemplo realmente usa o IN operador para encontrar posts com qualquer um dos termos, mas como esse é o padrão, você não precisa especificá-lo em seus argumentos.

Outro cenário é se você deseja consultar postagens que não possuem uma matriz de termos em uma taxonomia, o que você faz assim:

$args = array(
    'tax_query' => array(
        array(
            'taxonomy' => 'post_tag',
            'terms' => [14, 17],
            'operator' => 'NOT IN'
        )
    )
);

Aqui eu substituí o AND operador com NOT INo que significa que o WordPress encontrará postagens sem nenhum dos termos na matriz.

Observe que, se você preferir usar slugs em vez de IDs de termo, poderá fazê-lo com qualquer um desses cenários. O último exemplo ficaria assim:

$args = array(
    'tax_query' => array(
        array(
            'taxonomy' => 'post_tag',
            'field' => 'slug',
            'terms' => ['php', 'strings'],
            'operator' => 'NOT IN'
        )
    )
);

Consultando termos de várias taxonomias

Se você quiser trabalhar com mais de uma taxonomia, precisará criar mais de uma matriz. Vejamos o exemplo mais simples, para consultar postagens com um termo da taxonomia de categoria e um termo da taxonomia de tags:

$args = array(
    'tax_query' => array(
        'relation' => 'AND',
        array(
            'taxonomy' => 'category',
            'field' => 'slug',
            'terms' => ['tutorial']
        ),
        array(
            'taxonomy' => 'post_tag',
            'field' => 'slug',
            'terms' => ['javascript']
        )
    )
);

Aqui eu escrevi dois arrays aninhados: um para cada taxonomia, usando os mesmos argumentos que usei para os exemplos usando apenas uma taxonomia. Eu os precedi com o relation argumento. Você precisa incluir o relation argumento para dizer ao WordPress se ele está procurando por todos ou alguns dos posts produzidos por cada array. Isso funciona da seguinte forma:

• Se você usar 'relation' => 'AND'o WordPress buscará as postagens especificadas na primeira matriz e a segunda matriz. Portanto, no exemplo acima, apenas postagens com Ambas a tutorial lesma em category e a javascript lesma em post_tag será consultado.
• Se você usar 'relation' => 'OR'o WordPress irá buscar os posts gerados pelo primeiro array ou a segunda matriz. Então, neste caso, você receberá postagens com qualquer a tutorial lesma ou o javascript lesma (ou ambos).

Este é o código que você usaria se estivesse procurando por postagens com um dos dois slugs:

$args = array(
    'tax_query' => array(
        'relation' => 'OR',
        array(
            'taxonomy' => 'category',
            'field' => 'slug',
            'terms' => ['tutorial']
        ),
        array(
            'taxonomy' => 'post_tag',
            'field' => 'slug',
            'terms' => ['javascript']
        )
    )
);

Você também pode procurar mais de um termo em uma determinada taxonomia adicionando-o à matriz:

$args = array(
    'tax_query' => array(
        'relation' => 'OR',
        array(
            'taxonomy' => 'category',
            'field' => 'slug',
            'terms' => ['guide']
        ),
        array(
            'taxonomy' => 'post_tag',
            'field' => 'slug',
            'terms' => ['php', 'strings']
        )
    )
);

Ao combinar o relation argumento com consultas e também usando o operator argumento, você pode criar consultas sofisticadas. Os argumentos abaixo consultariam postagens com um termo de uma taxonomia, mas sem um termo de outra taxonomia:

$args = array(
    'orderby' => 'title',
    'tax_query' => array(
        'relation' => 'AND',
        array(
            'taxonomy' => 'category',
            'field' => 'slug',
            'terms' => ['tutorial'],
            'operator' => 'NOT IN'
        ),
        array(
            'taxonomy' => 'post_tag',
            'field' => 'slug',
            'terms' => ['php', 'math'],
            'operator' => 'AND'
        )
    )
);

Note que eu usei 'relation' => 'AND' aqui: se eu usasse ORele consultaria postagens com slug-two e mensagens sem slug-oneem vez de postagens que slug-two mas não slug-oneque é o que estou procurando.

Você poderia levar isso adiante para consultar os termos de suas taxonomias como quisesse: usando o operator argumento em ambas as consultas aninhadas ou adicionar uma consulta aninhada adicional aos termos de consulta em outra taxonomia.

Consultas de taxonomia aninhadas

É possível criar consultas de taxonomia aninhadas para criar filtros muito mais complexos para obter suas postagens. O suporte para taxonomias aninhadas foi adicionado ao núcleo do WordPress na versão 4.1. Era muito mais complicado ou absolutamente impossível obter resultados semelhantes mais cedo.

$args = array(
    'tax_query' => array(
        'relation' => 'OR',
        array(
            'taxonomy' => 'category',
            'field' => 'slug',
            'terms' => ['guide'],
        ),
        array(
            'relation' => 'AND',
            array(
                'taxonomy' => 'category',
                'field' => 'slug',
                'terms' => ['tutorial'],
            ),
            array(
                'taxonomy' => 'post_tag',
                'field' => 'slug',
                'terms' => ['php', 'strings'],
                'operator' => 'AND'
            )
        )
    )
);

A consulta acima selecionará postagens em category taxonomia com o guide slug ou postes que tenham o tutorial lesma sob category e ter o php, strings combinação de lesma sob post_tag.

Uma nota sobre o argumento fiscal

Você pode estar se perguntando por que eu não incluí o {tax} argumento, onde você simplesmente escreve seu argumento da seguinte forma:

$args = array(
    'taxonomy1' => 'slug-one'
);

Você pode estar familiarizado com essa maneira de consultar taxonomias se já fez isso no passado, mas agora está obsoleta e você não deve usá-la. Então fique com tax_query! Usando tax_query dá-lhe muito mais flexibilidade de qualquer maneira.

Resumo

Consultar taxonomias é um pouco mais complicado do que categorias e tags, pois você precisa se familiarizar com o tax_query argumento.

No entanto, como vimos, esse é um argumento muito poderoso que oferece muito escopo e flexibilidade para consultar seu banco de dados da maneira que desejar.

Este post foi atualizado com contribuições de Nitish Kumar. Nitish é um desenvolvedor web com experiência na criação de sites de comércio eletrônico em várias plataformas. Ele passa seu tempo livre trabalhando em projetos pessoais que facilitam sua vida cotidiana ou fazendo longas caminhadas noturnas com os amigos.