У сьогоднішній статті я розповім вам про те, як користуватися класом WP_User_Query для опитування користувачів WordPress.

Що таке WP_User_Query?

Ви напевно вже здогадалися про призначення WP_User_Query, просто прочитавши назву цього класу. Він призначений для отримання даних про користувачів.

Давайте подивимося, що про це класі йдеться в кодексі WordPress:

«WP_User_Query – це клас, визначений in wp-includes/user.php, який дозволяє опитувати таблиці ‘wp_users‘ і ‘wp_usermeta‘ в базі даних WordPress. Цей клас був представлений у версії WP 3.1 як альтернатива старому класу WP_User_Search»

Можна сказати, що WP_User_Query – це WP_Query для роботи з користувачами. Цей клас працює з wp_users і wp_usermeta, і призначений для побудови запитів до цих таблиць.

Тепер ми познайомимося з властивостями, методами і параметрами WP_User_Query.

Нагадування: «властивості» і «методи» — це те ж, що і «змінні» і «функції», які ми зазвичай визначаємо в PHP-класі.

Властивості WP_User_Query

Для класу WP_User_Query передбачено всього 7 властивостей. Але краще не змінювати значення, що зберігаються у цих властивостях. Ви можете отримувати їх значення, але не варто змінювати їх.

$query_vars

Зберігає в собі асоціативний масив змінних запиту і їх значень.

$results

Зберігає в собі дані, отримані в результаті виконання запиту про користувачів.

$query_fields

Це властивість, подібно наступним властивостям, зберігає в собі SQL-команди запиту.

$query_from

Зберігає в собі команду FROM.

$query_where

Зберігає в собі умова WHERE.

$query_orderby

Зберігає в собі команду ORDERBY, і використовується для сортування отриманих результатів (знайдених користувачів).

$query_limit

Містить у собі команду LIMIT, і використовується для обмеження кількості отриманих результатів (знайдених користувачів).

Методи WP_User_Query

В цьому класі всього 4 методу, і вони працюють за тим же принципом, що і в WP_Query.

Метод get()

Цей метод повертає змінну запиту.

Метод set()

Встановлює, а не отримує змінну запиту.

Метод get_results()

На відміну від WP_Query, клас WP_User_Query не працює з циклом. Замість цього потрібно використовувати метод get_results(), щоб отримати результати запиту і працювати з ними.

Метод get_total()

Повертає загальну кількість елементів (користувачів).

Параметри WP_User_Query

У WP_User_Query всього 17 параметрів, і вони дуже схожі на ті, які ми розглядали в статтях, присвячених класу WP_Query.

  • blog_id: ціле число, вказується ID блогу в мережах з декількома сайтами. За замовчуванням встановлюється ID поточного блогу;
  • role: рядок для визначення ролі користувача. Приймаються значення subscriber, author, contributor, author, editor, sanyok і будь-які інші власні значення;
  • include: масив ID користувачів, які потрібно включити в запит;
  • exclude: масив ID користувачів, які потрібно виключити з запиту;
  • search: рядкове значення, яке потрібно використовувати для пошуку по полях таблиці wp_users;
  • search_columns: масив стовпців таблиці wp_users. Приймає значення ID, user_login, user_url, user_email і user_nicename;
  • orderby: рядкове значення для сортування отриманих результатів. Приймаються значення ID, display_name, name/user_name, login/user_login, nicename/user_nicename, email/user_email, url/user_url, registered/user_registered, post_count і meta_value. За замовчуванням значення login;
  • order: рядок для визначення напряму сортування (ASC – за зростанням і DESC – за спаданням);
  • offset: кількість користувачів з самого початку, яких необхідно пропустити;
  • number: кількість користувачів, яких необхідно отримати і вивести;
  • count_total: логічний вираз (TRUE/FALSE) для включення і відключення підрахунку загальної кількості користувачів;
  • fields: рядок або масив, у якому вказується, які поля потрібно отримати з таблиці wp_users;
  • who: рядок (‘authors’ або ‘all’) для визначення, яких користувачів потрібно запитувати;
  • meta_key: рядок для визначення ключа довільного поля метаданих користувача;
  • meta_value: рядок для визначення значення довільного поля метаданих користувача;
  • meta_compare: рядок для установки оператора порівняння параметра ‘meta_value’. Приймає наступні значення: ‘=’, ‘!=’, ‘>‘, ‘>=‘, ‘

.

‘Editor’,
‘exclude’ => $exclude_list
);
// Довільний запит.
$my_user_query = new WP_User_Query( $args );
// Отримуємо результати запиту.
$editors = $my_user_query->get_results();
// Проводимо перевірку наявності результатів запиту.
if ( ! empty( $editors ) ) {
echo ‘

    ‘;
    // Проходимся по всім редакторам.
    foreach ( $editors as $editor ) {
    // Отримуємо дані про кожному редакторі.
    $editor_info = get_userdata( $editor->ID );
    // Виводимо ім’я редактора.
    echo ‘

  • ‘. $editor_info->display_name . ‘
  • ‘;
    }
    echo ‘

‘;
} else {
// Виводимо повідомлення «редакторів не знайдено» message.
echo __( ‘Редакторів не знайдено!’, ‘tutsplus’ );
}
?>

Здійснюємо пошук користувачів Gmail серед ваших авторів

Припустимо, що потрібно зібрати email-адреси тільки тих ваших авторів, які використовують Gmail.

Ось що потрібно зробити:

‘authors’,
// Пошук email-адреси, що закінчуються на `@gmail.com`.
‘search’ => ‘*@gmail.com’,
// Пошук тільки по підлозі `email`.
‘search_columns’ => array( ’email’ ),
// Отримуємо тільки поле `email`.
‘fields’ => ’email’
);
// Довільний запит.
$my_user_query = new WP_User_Query( $args );
// Отримуємо результати запиту.
$gmailers = $my_user_query->get_results();
?>

На завершення

Між WP_Query і WP_User_Query багато спільного, і це робить клас WP_User_Query більш простим для розуміння.

Поділіться своїми думками зі мною та іншими читачами. Якщо вам сподобалася стаття, обов’язково поділіться нею з друзями.

Побачимося в наступних статтях з цієї серії!

Переклад статті «Mastering WP_User_Query» був підготовлений дружною командою проекту Сайтостроение від А до Я.