Jak wyświetlić listę użytkowników w WordPress? (WP_User_Query)

W ekosystemie WordPressa to WP_Query zgarnia całą chwałę, ale to WP_User_Query rządzi światem serwisów społecznościowych, intranetów i platform członkowskich.

Niezależnie od tego, czy budujesz prostą stronę “Nasz Zespół” (Team Page), czy skomplikowaną wyszukiwarkę “Znajdź Lekarza” z tysiącami specjalistów, poleganie na wtyczkach typu Ultimate Member do warstwy prezentacji jest często przesadą – i wąskim gardłem wydajnościowym.

W tym poradniku pominiemy interfejsy graficzne i zbudujemy wydajne, bezpieczne zapytania o użytkowników bezpośrednio w PHP. Omówimy granularne filtrowanie, cache’owanie wydajnościowe i krytyczne środki bezpieczeństwa, aby zapobiec wyciekom danych.

1. development() vs. WP_User_Query

Tak jak get_posts() jest nakładką na WP_Query, tak development() jest skonfigurowaną nakładką na WP_User_Query.

• Używaj development() do prostych list (np. “Pokaż mi 5 administratorów”). Zwraca tablicę obiektów WP_User.
• Używaj WP_User_Query, gdy potrzebujesz zaawansowanych manipulacji SQL, szczegółowej logiki sortowania (‘orderby’) lub inspekcji nagłówków zapytania/wyników bezpośrednio.

W 95% przypadków będziemy używać tablicy argumentów, która ma zastosowanie do obu funkcji.

2. Podstawy: Budowa Strony Zespołu

Załóżmy, że chcemy wyświetlić siatkę pracowników (Redaktorów i Autorów) posortowaną według ich wyświetlanej nazwy.

$args = [
    'role__in'    => ['editor', 'author'],
    'orderby'     => 'display_name',
    'order'       => 'ASC',
    'number'      => 12, // Limit paginacji
    '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. Zaawansowane Filtrowanie (Meta Queries)

Tutaj WP_User_Query błyszczy. Wyobraź sobie, że masz katalog programistów i chcesz znaleźć tych, którzy:

1. Są z “Warszawy”.
2. Mają profil oznaczony jako “Publiczny”.
3. Mają “PHP” na liście umiejętności.

$args = [
    'role'       => 'subscriber',
    'meta_query' => [
        'relation' => 'AND',
        [
            'key'     => 'city',
            'value'   => 'Warszawa',
            'compare' => '='
        ],
        [
            'key'     => 'is_public_profile',
            'value'   => '1',
            'compare' => '='
        ],
        [
            'key'     => 'skills',
            'value'   => 'PHP',
            'compare' => 'LIKE' // Wolne, ale skuteczne dla zserializowanych tablic
        ]
    ]
];

[!WARNING] Alert Wydajnościowy: Odpytywanie wp_usermeta jest kosztowne. W przeciwieństwie do wp_posts, tabele użytkowników rzadko są optymalnie indeksowane pod kątem złożonego filtrowania. Dla katalogów >10,000 użytkowników, rozważ przeniesienie indeksu wyszukiwania do Elasticsearch (przez ElasticPress) lub użycie własnej tabeli SQL.

4. Optymalizacja Wydajności

Odpytując użytkowników na stronie o dużym ruchu, musisz oszczędnie gospodarować zasobami bazy danych.

A. Ogranicz Zwracane Pola (Fields)

Domyślnie WordPress pobiera każdą możliwą daną o użytkowniku (wszystkie metadane). Jeśli potrzebujesz tylko imion i e-maili, powiedz WordPressowi, by był lekki.

$args = [
    'role'   => 'subscriber',
    'number' => 100,
    'fields' => ['ID', 'display_name', 'user_email'], // Zwraca obiekty stdClass, nie WP_User
];

Wynik: Zużycie pamięci RAM spada drastycznie.

B. Policz Użytkowników Bez Ich Ładowania

Jeśli chcesz tylko pokazać “Mamy 500 członków!”, nie ładuj obiektów członków.

$args = [
    'role'   => 'subscriber',
    'fields' => 'ID', // Pobierz tylko ID
];
$query = new WP_User_Query($args);
$count = $query->get_total(); // Używa logiki SQL_CALC_FOUND_ROWS

Lub dla ekstremalnej szybkości (ignorując złożone filtry), użyj count_users():

$count = count_users();
echo "Mamy " . $count['total_users'] . " użytkowników.";

5. Bezpieczeństwo: Zagrożenie “User Enumeration”

Domyślnie WordPress jest dość “dziurawy”, jeśli chodzi o dane użytkowników.

1. Nie ujawniaj Loginów: Nigdy nie wykonuj echo $user->user_login. To połowa klucza potrzebnego do zhakowania konta administratora. Zawsze używaj display_name lub user_nicename.
2. Ukrywaj E-maile: O ile to nie jest wewnętrzny intranet, nigdy nie wypisuj user_email w kodzie HTML, aby uniknąć botów spamujących.

Blokowanie Archiwów Autora

Hakerzy często skanują /?author=1, /?author=2, aby odkryć nazwy użytkowników. Jeśli budujesz stronę firmową, gdzie użytkownicy nie potrzebują publicznych archiwów, wyłącz tę trasę.

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

6. Podsumowanie

Budowanie własnego katalogu użytkowników daje pełną kontrolę nad wydajnością i bezpieczeństwem.

1. Używaj parametru fields, aby zmniejszyć ślad pamięci.
2. Cache’uj wyniki używając Transients API, jeśli katalog nie zmienia się co godzinę.
3. Sanityzuj dane wyjściowe bezlitośnie (zawsze esc_html).
4. Chroń prywatność, ukrywając loginy i e-maile.

Użytkownicy w WordPressie to encje tak samo jak posty – zacznij ich odpytywać z tą samą precyzją.