Dominando WP_User

Portuguese (Português) translation by João Fagner (you can also view the original English article)

Após todos esses tutoriais sobre a classe WP_Query, estaremos terminando nossa aventura— mas isso não significa que terminamos com a série! É hora de conhecer as classes irmãos e irmãs do WP_Query: WP_User_Query, WP_Comment_Query, WP_Meta_Query e WP_Date_Query.

Nesta parte, vamos aprender sobre como usar a classe WP_User_Query para usuários de consulta no WordPress.

Vamos começar!

O que é WP_User_Query?

Provavelmente, você começa com a idéia de que WP_User_Query meramente está lendo o seu nome. Sim, ninguém esperaria ver WP_User_Query trabalhando com o widget "Tag Cloud" — é uma classe que executa consultas sobre usuários no WordPress.

Vejamos o que diz o WordPress Codex sobre a classe WP_User_Query:

WP_User_Query é uma classe definida em wp-inclui/user.php, que permite consultar tabelas do banco de dados do WordPress 'wp_users' e 'wp_usermeta'. Esta classe foi introduzido na versão 3.1 e como resultado, a classe WP_User_Search está depreciada.

Em essência podemos dizer que "WP_User_Query é WP_Query são para os usuários". Ele funciona com wp_users e wp_usermeta para a consulta de usuários e de seus metadados.

Agora vamos ver o que está sob o capô e aprender sobre as propriedades WP_User_Query, métodos e parâmetros. Então vamos ver como funciona através de alguns exemplos.

Dica Rápida: Falamos sobre isso ao introduzir as propriedades e métodos para a classe WP_Query, mas direi novamente como um lembrete rápido: "Propriedades" e "Métodos" são meramente "variáveis" e "funções" que são definidas dentro de uma classe PHP.

Propriedades do WP_User_Query

Há apenas sete Propriedades para aprender sobre a classe WP_User_Query. Lembre-se: Que elas NÃO devem ser usadas para alterar seus valores. Você pode buscar seus valores, mas é melhor não alterá-los.

`$query_vars`

Esta propriedade armazena um array associativo de variáveis de consulta e seus valores.

`$results`

Esta propriedade tem o número de itens (usuários neste caso) foi encontrado para a consulta.

`$query_fields`

Esta propriedade, semelhante às seguintes propriedades, armazena as cláusulas SQL para campos de retorno.

`$query_from`

Esta propriedade armazena a cláusula FROM da consulta.

`$query_where`

Esta propriedade armazena a cláusula WHERE da consulta.

`$query_orderby`

Esta propriedade armazena a cláusula ORDERBY para a consulta e é usada para ordenar a lista de usuários retornado.

`$query_limit`

Esta propriedade armazena a cláusula de LIMIT para a consulta e é usada para limitar o número de usuários retornado.

Métodos de WP_User_Query

Lembre-se dos métodos da classe WP_Query? Bem, essa classe tem apenas quatro métodos e trabalham como os métodos de WP_Query. Vejamos rapidamente porque cada um existe.

O Método `get()`

Esse método busca simplesmente uma variável de consulta da consulta.

O Método `set()`

Contrario ao metodo acima, este método define uma variável de consulta em vez de ficar com ele.

O Método `get_results()`

Ao contrário de WP_Query a classe WP_User_Query não funciona com um "loop". Em vez disso, você precisa usar o método get_results() para obter os resultados da consulta e trabalhá-los.

O Método `get_total()`

Este pequeno método retorna o número total de itens (usuários) para a consulta.

Parâmetros de WP_User_Query

Como a classe WP_Query, WP_User_Query tem os parâmetros que você precisa saber. Mas enquanto WP_Query tem um grande número de parâmetros (mais de 50!), WP_User_Query tem apenas 17 parâmetros com que se preocupar — e eles são muito parecidos com os em WP_Query, então se você estiver familiarizado com aqueles parâmetros não deverá ter nenhum aborrecimento em aprende-los.

blog_id: Um inteiro para especificar o ID de um blog em redes de multsite. O padrão é o Blog atual.
role: Uma string para o estado da role (função ou papel do usuário no WordPress). Aceita o subscriber, author, contributor, author,editor, administrator e qualquer função de usuário customizada-criado.
include: uma array de IDs para incluir na consulta de usuário.
exclude: Um array de IDs de usuários para excluir da consulta.
search: Um valor para buscar por campos da tabela wp_users.
search_columns: Um array de colunas da tabela wp_users. Aceita ID, user_login, user_url, user_email e user_nicename.
orderby: Uma string para indicar como classificar os usuários retornados. Aceita ID, display_name, name/user_name,login/user_login, nicename/user_nicename,email/user_email, url/user_url,registered/user_registered, post_count e meta_value. O padrão é o login.
order: Uma string para definir a ordem de ascendente (ASC) ou descendente (DESC).
offset: Um inteiro para especificar o número de usuários a passar por cima.
number: Um número inteiro para definir o número de usuários para retornar.
count_total: Um valor booleano (TRUE/FALSE) para indicar se deseja contar o número total de usuários encontrados.
fields: uma string de caracteres ou array para decidir quais campos para retornar da tabela wp_users.
who: Uma string (tanto authors (autores) ou all (todos), são os valores padrão) para indicar quais usuários para consulta.
meta_key: Uma string para o estado de uma chave de campo de meta de usuário personalizada.
meta_value: Uma string para um valor do campo personalizado usuário meta do estado.
meta_compare: Uma string para definir um operador para testar o parâmetro 'meta_value'. Aceita: '=', '!=', '>', '>=', '<', '<=', 'LIKE','NOT LIKE', 'IN', 'NOT IN', 'BETWEEN', 'NOT BETWEEN', 'EXISTS' e 'NOT EXISTS'. O padrão é '='.
meta_query: Um array para criar uma consulta cheia de dados meta, usando chaves semelhantes aos acima:

key: Uma string para definir uma chave (key) de campo personalizado.
value: Uma string ou uma array para definir um valor do campo personalizado (ou valores).
compare: Uma string para definir o operador de comparação. Aceita os mesmos valores do meta_compare acima.
type: Uma string para definir o tipo de campo personalizado. Aceita NUMERIC, BINARY, CHAR, DATE, DATETIME,DECIMAL, SIGNED, TIME, e UNSIGNED. O padrão é CHAR.

Experimentando WP_User_Query Com Alguns Exemplos

Agora que vimos como funciona o WP_User_Query, vamos fazer alguns exemplos para aprender a usá-lo.

Listando Todos os Editores, Exceto Lisa

Digamos que você deseja listar seus editores para os seus leitores, mas você lembra que um dos seus editores, Lisa, concordou em trabalhar com você, na condição de anonimato, então você precisa deixá-la na lista de "Editors". Aqui está como você pode construir a consulta:

<?php

// Add Lisa's user id,  14, in an array.
$exclude_list = array( 14 );

$args = array(
    'role' => 'Editor',
    'exclude' => $exclude_list
);

// Custom query.
$my_user_query = new WP_User_Query( $args );

// Get query results.
$editors = $my_user_query->get_results();

// Check for editors
if ( ! empty( $editors ) ) {

    echo '<ul class="editors-list">';

        // Loop over editors.
        foreach ( $editors as $editor ) {
    
            // Get each editor's data.
            $editor_info = get_userdata( $editor->ID );
    
            // Show editor's name.
            echo '<li>' . $editor_info->display_name . '</li>';
    
        }

    echo '</ul>';

} else {

    // Display "no editors found" message.
    echo __( 'No editors found!', 'tutsplus' );

}

?>

Pesquisa Por Usuários de Gmail Entre Seus Autores

Digamos que você deseja coletar endereços de e-mail dos seus autores que usam um endereço do Gmail. Aqui está o que você pode fazer:

<?php

// Setup arguments.
$args = array(
    // Search for authors only.
    'who' => 'authors',
    // Search for email addresses ending with `@gmail.com`.
    'search' => '*@gmail.com',
    // Search the `email` field only.
    'search_columns' => array( 'email' ),
    // Return the `email` field only.
    'fields' => 'email'
);

// Custom query.
$my_user_query = new WP_User_Query( $args );

// Get query results.
$gmailers = $my_user_query->get_results();

?>

Embrulhando Tudo

Como você pode ver, existem apenas algumas diferenças entre WP_Query e WP_User_Query, as diferenças realmente fazem WP_User_Query ser mais fácil de entender. Espero ter ajudado vocês a terem aprendido mais sobre essa classe do WordPress.

Tem algo para acrescentar a este artigo? Compartilhe seus pensamentos na seção de comentários abaixo. E se você gostou do artigo, não se esqueça de compartilhar com seus amigos.

Nos vemos na próxima parte da série!

Seja o primeiro a saber sobre novas traduções–siga @tutsplus_pt no Twitter!

1	<?php
2
3	// Add Lisa's user id, 14, in an array.
4	$exclude_list = array( 14 );
5
6	$args = array(
7	'role' => 'Editor',
8	'exclude' => $exclude_list
9	);
10
11	// Custom query.
12	$my_user_query = new WP_User_Query( $args );
13
14	// Get query results.
15	$editors = $my_user_query->get_results();
16
17	// Check for editors
18	if ( ! empty( $editors ) ) {
19
20	echo '<ul class="editors-list">';
21
22	// Loop over editors.
23	foreach ( $editors as $editor ) {
24
25	// Get each editor's data.
26	$editor_info = get_userdata( $editor->ID );
27
28	// Show editor's name.
29	echo '<li>' . $editor_info->display_name . '</li>';
30
31	}
32
33	echo '</ul>';
34
35	} else {
36
37	// Display "no editors found" message.
38	echo __( 'No editors found!', 'tutsplus' );
39
40	}
41
42	?>

Dominando WP_User_Query

O que é WP_User_Query?

Propriedades do WP_User_Query

$query_vars

$results

$query_fields

$query_from

$query_where

$query_orderby

$query_limit