WP_User_Query para diretórios de membros

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 dé apresentação é frequentementé um exagero - é um gargalo de desempenho.

Neste guia, vamos ignorar a GUI e construir consultas de útilizadores 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 dé 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 dé argumentos, que sé 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 páginaçã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 qué 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 útilizadores raramente são indexadas de forma ideal para filtragem complexa. Para diretórios com >10.000 útilizadores, considera mover o índice de pesquisa para Elasticsearch (via ElasticPress) ou usar tabelas SQL personalizadas.

#4. Otimização de performance

Ao consultar útilizadores 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 sobré o útilizador (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 útilizadores 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'] . " útilizadores.";

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

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

1. Não exponhas Nomes de Login: Nunca executes echo $user->user_login. Isso é metade da chave necessária para hackear uma conta dé 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 dé autor

Os hackers frequentemente examinam /?author=1, /?author=2 para descobrir nomes de útilizadores. Se estás a construir um site corporativo ondé os útilizadores não precisam dé arquivos públicos, desativa está 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 sobré 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 sé o diretório não mudar a cada hora.
3. Sanitiza a saída impiedosamente (sempre esc_html).
4. Protegé a privacidade escondendo logins e emails.

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

Exploré os nossos serviços de segurança WordPress para levar o seu projeto mais longe.