WP_User_Query

Итак, у меня уже есть подробный пост про класс WP_Query, вот только WP_Query нужен для вывода или фильтра постов, а WP_User_Query — для вывода и фильтра пользователей. Также он позволяет вывести некоторую информацию о полученных пользователях.

Правильное использование класса

Сейчас я рассмотрю простой пример, чтобы вам было понятно, как всё устроено, а затем уже более детально углублюсь в описание параметров, объекта WP_User и пр.

/*
 * Массив $params содержит параметры вывода пользователей
 */
$params = array(
    'role' => 'Subscriber', // роль Подписчик
    'number' => 10 // количество выводимых пользователей - 10
);
 
/*
 * Создаем новый объект с пользователями
 */
$uq = new WP_User_Query( $params );
 
/*
 * Сначала проверяем, что объект не пустой, т е что пользователи соответствующие заданным в $params параметрам, существуют
 */
if ( ! empty( $uq->results ) ) {
 
    /*
     * Для каждого пользователя запускаем цикл
     */
    foreach ( $uq->results as $u ) {
        /*
         * $u в данном случае это объект пользователя WP_User
         * этот объект содержит много разной информации о пользователе, рассмотрим подробнее дальше в посте
         * в этом же примере просто выведем емаилы пользователей
         */
        echo '<p>' . $u->user_email . '</p>';
    }
} else {
    echo 'Пользователей по заданным критериям не найдено.';
}

Параметры класса WP_User_Query

А сейчас я постараюсь максимально подробно описать все параметры, которые принимает класс WP_User_Query.

Роли

role

(строка) роль пользователей, которых будем выводить.

// выведем к примеру всех редакторов $uq = new WP_User_Query( array( 'role' => 'Editor' ) );

Параметры вывода либо исключения из вывода конкретных пользователей

include

(массив) массив, состоящий из ID-ов пользователей, которых хотим получить.

// простой пример параметра include $uq = new WP_User_Query( array( 'include' => array(50, 58) ) );

exclude

(целое число|массив) число или массив, состоящий из ID-ов пользователей, которых хотим исключить из результатов.

// простой пример параметра exclude $uq = new WP_User_Query( array( 'exclude' => array(71, 58) ) );

// усложним - выведем всех администраторов, исключив при этом главного администратора (с ID = 1 ) $uq = new WP_User_Query( array( 'role' => 'Administrator', 'exclude' => 1 ) );

Параметры поиска пользователей

search

(строка) строка поиска. Если вам нужно сделать поиск только по части строки, используйте *. Примеры: Misha, Mis*, *sha, *ish*.

search_columns

(массив) области поиска — это список колонок базы данных таблицы с пользователями, по которым нужно производить поиск:

• ID — понятное дело, ID пользователей,
• login или user_login — имя пользователя (логин),
• nicename или user_nicename — колонка найснейм,
• email или user_email — емайлы пользователей,
• url или user_url — URL сайтов пользователей.

// ищем всех юзеров, у которых в логине или емайле содержится слово misha $uq = new WP_User_Query( array( 'search' => '*misha*', 'search_columns' => array('user_email', 'user_nicename', 'user_login') ) );

Параметры количества пользователей

number

(целое число) сколько юзеров нужно вывести (по умолчанию — все).

offset

(целое число) сколько пользователей нужно пропустить от начала полученного списка.

// выводим четверых пользователей, пропустив при этом первых двух $uq = new WP_User_Query( array( 'number' => 4, 'offset' => 2 ) );

Сортировка пользователей

orderby

(строка) Сортировать по:

• ID — по ID,
• display_name — по отображаемому имени (задается самим пользователем в админке),
• name, user_name — по имени пользователя,
• login, user_login — по логину пользователя (по умолчанию),
• nicename, user_nicename — по найснейму,
• email, user_email — по адресу электронной почты,
• url, user_url — по URL сайтов пользователей,
• registered, user_registered — по дате регистрации пользователей,
• post_count — по количеству публикаций,
• meta_value — по значению произвольного поля (параметр meta_key в данном случае обязателен — описан чуть ниже),

order

(строка) Порядок сортировки, ASC — по возрастанию (установлен по умолчанию), DESC — по убыванию.

Метаданные пользователей

meta_key

(строка) название элемента метаданных юзера, ключ.

meta_value

(строка) значение указанного элемента метаданных meta_key.

meta_compare

(строка) оператор сравнения. Доступны = (по умолчанию) и !=, > и <, >= и <=, BETWEEN и NOT BETWEEN, EXISTS и NOT EXISTS, LIKE и NOT LIKE, IN и NOT IN (большинство этих операторов описаны в действии в этой статье).

meta_query

(массив) По сути выполняет те же функции, что и предыдущие параметры, но при этом позволяет задавать несколько условий и устанавливать вид связи между ними.

key

аналог meta_key,

value

аналог meta_value,

compare

аналог meta_compare,

type

(строка) тип данных, содержащихся в value, возможны значения CHAR (по умолчанию), BINARY, NUMERIC, DECIMAL, DATE, TIME, DATETIME, SIGNED, UNSIGNED.

relation

(строка) соотножение условий, принимает значения:

• OR — ИЛИ (должно выполняться хотя бы одно из заданных условий),
• AND — И (должны выполняться все заданные условия).

Очень много примеров по meta_query есть в этой статье (там конечно meta_query используется для вывода постов, но для пользователей оно работает точно так же).

И один пример всё же тут:

$params = array(
    'meta_query' => array(
        'relation' => 'AND', // соотношение И, значит должны выполняться оба условия
        array( // условие 1, пользователь должен быть из Москвы
            'key'     => 'gorod',
            'value'   => 'Moscow',
            'compare' => '=' // можно не указывать, это и так является значением по умолчанию
        ),
        array( // условие 2, возвраст пользователя должен быть от 19 до 29 лет
            'key'     => 'vozrast',
            'value'   => array( 19, 29 ), // промежуток подходящих значений
            'type'    => 'numeric', // числовое значение
            'compare' => 'BETWEEN' // значение параметра должно попадать в указанный промежуток
        )
    )
 );
$uq = new WP_User_Query( $params );

Сами задаем необходимые возвращаемые значения

fields

(строка|массив) может принимать следующие значения:

• ID — возвращает массив, состоящий из ID пользователей,
• all (по умолчанию), all_with_meta — возвращает всю информацию о пользователях в виде массива объектов WP_User.

$uq = new WP_User_Query( array( 'fields' => 'ID' ) ); // Array ( [0] => 1 [1] => 4 [2] => 3 [3] => 2 )

Методы и свойства класса WP_User_Query

Итак, начнем с того, что создадим объект WP_User_Query:

// Я просто взял пример из предыдущей главы
$uq = new WP_User_Query( array( 'fields' => 'ID' ) );

В данном случае $uq — это наш объект, давайте глянем, какие у него есть методы и свойства.

Свойства

$uq->results

Содержит либо массив ID-ов пользователей (при fields равным ID), либо массив из объектов WP_User пользователей. Этот метод уже был рассмотрен в самом первом примере.

$uq->query_vars

Массив параметров объекта (да, это именно те параметры которые задаем мы, я описывал их в предыдущем шаге).

echo $uq->query_vars["fields"]; // ID

$uq->total_users

Строка, общее количество полученных пользователей.

echo 'Найдено пользователей: ' . $uq->total_users;

$uq->query_fields
$uq->query_from
$uq->query_where
$uq->query_orderby
$uq->query_limit

Куски SQL-запросов к таблице wp_users. Их можно вывести или как-то модифицировать, например при помощи фильтра pre_user_query.

Методы

get()

Позволяет получить любой из параметров $uq->query_vars, например:

echo $uq->get('fields');

set()

Позволяет изменить любой из параметров $uq->query_vars:

$uq->set('fields', 'all');

get_results()

Возвращает массив пользователей $uq->results.

get_total()

Возвращает общее число полученных пользователей.

echo $uq->get_total();

Параметры объекта пользователя WP_User

Для удобства и наглядности давайте рассмотрим параметры пользователей на примере.

/*
 * В плане параметров именно WP_User_Query особо заморачиваться не будем, пусть будет просто 10 пользователей
 */
$uq = new WP_User_Query( array( 'number' => 10 ) );
 
echo '<h3>Пользователи (всего: ' . $uq->total_users . ')</h3>'; // также можно юзать $uq->get_total()
 
/*
 * Пустой объект нам ни к чему, поэтому создаем эту проверку
 */
if ( ! empty( $uq->results ) ) {
 
    /*
     * Запускаем цикл (актуально только если параметр fields = all  (он стоит по умолчанию) или all_with_meta
     */
    foreach ( $uq->results as $u ) {
        /*
         * $u в данном случае это и есть объект пользователя, давайте поглядим, какие у него параметры
         */
        echo '<p>' . $u->ID . '</p>'; // ID
        echo '<p>' . $u->user_login . '</p>'; // логин
        echo '<p>' . $u->first_name . '</p>'; // имя
        echo '<p>' . $u->last_name . '</p>'; // фамилия
        echo '<p>' . $u->user_pass . '</p>'; // хэш пароля
        echo '<p>' . $u->user_nicename . '</p>'; // найснейм
        echo '<p>' . $u->user_url . '</p>'; // урл
        echo '<p>' . $u->user_registered . '</p>'; // дата регистрации
        echo '<p>' . $u->user_activation_key . '</p>'; // ключ активации
        echo '<p>' . $u->user_status . '</p>'; // статус пользователя
        echo '<p>' . $u->display_name . '</p>'; // отображаемое имя
        echo '<p>' . $u->user_email . '</p>'; // емайл
        print_r( $u->caps ); // роль пользователя
        print_r( $u->allcaps ); // возможности пользователя
        // благодаря массиву allcaps мы можем проверить любую возможность пользователя, например:
        if( $u->allcaps['edit_posts'] ) {
            echo 'Этот пользователь может редактировать посты.';
        }
    }
}

Тема довольно обширная, если вы считаете, что следует более подробно рассмотреть какой-либо момент, пожалуйста, напишите об этом в комментариях — я постараюсь вам всё объяснить и показать.