Dominar wp_User_Query: Construir um diretório de membros escalável em WordPress

No ecossistema WordPress, WP_Query recebe toda a glória, mas WP_User_Query governa o mundo dos sites de membros, intranets e plataformas comunitárias.

Estejas tu a construir uma página simples de “A Nossa Equipa” ou um motor de busca complexo de “Encontrar um Médico” com milhares de profissionais, depender de plugins como Ultimate Member para a camada de apresentação é frequentemente um exagero - e um gargalo de desempenho.

Neste guia, vamos ignorar a GUI e construir consultas de utilizadores eficientes e seguras diretamente em PHP. Vamos abordar filtragem granular, cache de desempenho e medidas de segurança críticas para evitar fugas de dados.

1. Development() vs. Wp_User_Query

Assim como get_posts() é um invólucro para WP_Query, development() é um invólucro pré-configurado para WP_User_Query.

• Usa development() para listas simples (ex: “Mostra-me 5 administradores”). Retorna um array de objetos WP_User.
• Usa WP_User_Query quando precisas de manipulações SQL avançadas, lógica ‘orderby’ detalhada ou inspeção direta dos cabeçalhos/resultados da consulta.

Para 95% dos casos de uso, usaremos o array de argumentos, que se aplica a ambos.

2. O básico: Construir uma página de equipa

Digamos que queremos exibir uma grelha de funcionários (Editores e Autores) ordenados pelo seu nome de exibição.

$args = [
    'role__in'    => ['editor', 'author'],
    'orderby'     => 'display_name',
    'order'       => 'ASC',
    'number'      => 12, // Limite de paginação
    'paged'       => 1,
];

$user_query = new WP_User_Query($args);
$results    = $user_query->get_results();

if (!empty($results)) {
    echo '<div class="team-grid">';
    foreach ($results as $user) {
        $avatar = get_avatar($user->ID, 128);
        $name   = esc_html($user->display_name);
        $bio    = esc_html(get_user_meta($user->ID, 'description', true));
        
        echo "<article class='team-member'>
                <figure>{$avatar}</figure>
                <h3>{$name}</h3>
                <p>{$bio}</p>
              </article>";
    }
    echo '</div>';
}

3. Filtragem avançada (meta queries)

É aqui que o WP_User_Query brilha. Imagina que tens um diretório de programadores e queres encontrar aqueles que:

1. Estão baseados em “Lisboa”.
2. Têm o perfil marcado como “Público”.
3. Têm “PHP” listado como competência.

$args = [
    'role'       => 'subscriber',
    'meta_query' => [
        'relation' => 'AND',
        [
            'key'     => 'city',
            'value'   => 'Lisboa',
            'compare' => '='
        ],
        [
            'key'     => 'is_public_profile',
            'value'   => '1',
            'compare' => '='
        ],
        [
            'key'     => 'skills',
            'value'   => 'PHP',
            'compare' => 'LIKE' // Lento, mas eficaz para arrays serializados
        ]
    ]
];

[!WARNING] Alerta de Performance: Consultar wp_usermeta é dispendioso. Ao contrário de wp_posts, as tabelas de utilizadores raramente são indexadas de forma ideal para filtragem complexa. Para diretórios com >10.000 utilizadores, considera mover o índice de pesquisa para Elasticsearch (via ElasticPress) ou usar tabelas SQL personalizadas.

4. Otimização de performance

Ao consultar utilizadores num site de tráfego elevado, deves ser poupado com os recursos da base de dados.

A. Limita os campos de retorno (fields)

Por defeito, o WordPress procura cada pedaço de dados sobre o utilizador (todos os metadados). Se precisas apenas de nomes e emails, diz ao WordPress para ser leve.

$args = [
    'role'   => 'subscriber',
    'number' => 100,
    'fields' => ['ID', 'display_name', 'user_email'], // Retorna objetos stdClass, não WP_User
];

Resultado: O uso de memória cai drasticamente.

B. Conta utilizadores sem os carregar

Se queres apenas mostrar “Temos 500 membros!”, não carregues os objetos dos membros.

$args = [
    'role'   => 'subscriber',
    'fields' => 'ID', // Busca apenas IDs
];
$query = new WP_User_Query($args);
$count = $query->get_total(); // Usa a lógica SQL_CALC_FOUND_ROWS

Ou para velocidade extrema (ignorando filtros complexos), usa count_users():

$count = count_users();
echo "Temos " . $count['total_users'] . " utilizadores.";

5. Segurança: A ameaça de “user enumeration”

Por defeito, o WordPress tem algumas “fugas” no que toca a dados de utilizadores.

1. Não exponhas Nomes de Login: Nunca executes echo $user->user_login. Isso é metade da chave necessária para hackear uma conta de administrador. Usa sempre display_name ou user_nicename.
2. Esconde Emails: A menos que seja uma intranet interna, nunca mostres user_email no código fonte HTML para evitar bots de spam.

Bloquear arquivos de autor

Os hackers frequentemente examinam /?author=1, /?author=2 para descobrir nomes de utilizadores. Se estás a construir um site corporativo onde os utilizadores não precisam de arquivos públicos, desativa esta rota.

// Adicionar ao functions.php
add_action('template_redirect', function() {
    if (is_author()) {
        wp_redirect(home_url(), 301);
        exit;
    }
});

6. Resumo

Construir o teu próprio diretório de membros dá-te controlo total sobre a performance e segurança.

1. Usa o parâmetro fields para reduzir a pegada de memória.
2. Faz cache dos resultados usando a API Transients se o diretório não mudar a cada hora.
3. Sanitiza a saída impiedosamente (sempre esc_html).
4. Protege a privacidade escondendo logins e emails.

Os utilizadores no WordPress são entidades tal como os posts - começa a consultá-los com a mesma precisão.