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 'Этот пользователь может редактировать посты.';
		}
	}
}

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

Подпишитесь, чтобы раз в неделю получать свежие статьи с блога по email.

Смотрите также

Комментарии 13

  • campusboy2 апреля 2015 в 00:04 #

    напиишите об этом в комментариях
    Ошибка :) Вопросов пока нет! Экспериментирую.

  • Егор19 октября 2015 в 20:10 #

    День добрый. Возник вопрос
    А если у пользователя роль читатель, как сделать, что-бы он был автором некоторого количества постов? И выводился автоматически как WP как автор поста?

    Есть сайт анекдотов, там обычная форма контактов, через которую зарегистрированный как читатель пользователь отправляет анекдоты. А уже админ модерирует и публикует. Конкурс, выставляются рейтинги лучшим анекдотам и их авторам.

    Большая часть народа просто даже представления не имеют, что такое админка и как там публиковаться. А так шлют.

    Я примерно знаю как показать саму форму контактов только зарегистрированным пользователям, через body_class() А как вышеописанное сделать?

    • Миша20 октября 2015 в 07:10 #

      Добрый день!
      Если пользователь зарегистрирован, вы всегда через код можете поставить ему роль участника даже без его ведома.

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

  • Егор20 октября 2015 в 14:10 #

    Здравствуйте. Они регистрируются как читатели, сами. И через форму, в сайдбаре появляется контактная форма для зарегистрированных, отправляют анекдоты, а модератор публикует.

    Я вот не знаю, может поставить пользователям роль автора, а вкладки в админке убрать? Что-бы им можно было редактировать профиль, задавать никнейм и все?

    В исходный код темы лучше не лезть. Тема премиум и обновляется постоянно. Как вариант-дополнение файла functions, через альтернативный functions, который будет в директории плагинов. CSS там есть кастомный.

    • Миша21 октября 2015 в 08:10 #

      Я вот не знаю, может поставить пользователям роль автора, а вкладки в админке убрать? Что-бы им можно было редактировать профиль, задавать никнейм и все?

      Вариант.

      Как вариант-дополнение файла functions, через альтернативный functions, который будет

      Почитайте про дочерние темы.

      • Егор21 октября 2015 в 14:10 #

        Да я итак знаю про дочерние темы. Зачем? CSS кастомный есть. Сделать еще custom-functions.php плагином. Тема итак тяжелая, нужно будет оптимизировать. Вобщем тоже затрудняетесь? :)

        • Миша22 октября 2015 в 07:10 #

          В предыдущем комментарии решение уже есть :) А про дочерние - там не только style.css но и functions.php можно добавить.

  • Егор22 октября 2015 в 14:10 #

    Ну да, я посоветоваться и хотел. Создавал я дочерние темы.

  • Егор22 октября 2015 в 19:10 #

    Да, сейчас сравнил скорость загрузки дочерней темы, и просто файла my-functions из директории плагинов, скорость одинаковая. Я ступил, файлы ведь взаимозаменимые, кроме style и functions.
    Вопросов по пользователям еще куча, никогда с ними не приходилось работать серьезно.

  • Егор24 октября 2015 в 05:10 #

    Спасибо. Я решил дочернюю тему ставить. Уже поставил. Сейчас пока вывожу там рейтинги (звездочки) и прочее.
    А по пользователям, если я убираю вкладки из админки, то по ссылке все равно можно перейти на нужную, если знать адрес :) Закрыть бы как-то полностью? И еще появляется в админке у нового пользователя сообщение, типа сообщите админу, что нужно установить плагин woocommers. Хотя там этот плагин не нужен совсем. Тема Sahifa. Но это я в css попробую закрыть.

  • campusboy16 декабря 2015 в 20:12 #

    WP_User_Query кажется слабоватым, относительно WP_Query :) К примеру, как:
    1) вывести список пользователей, у которых есть посты;
    2) вывести список пользователей, у которых есть посты в определенной категории;
    3) самое крутое - как вывести список пользователей, отсортированных по дате добавления их поста в определенную категорию, да ещё и пагинацией.

    Всё это получается, но приходится запускать несколько foreach с get_post, что явно нагружает базу запросами :(

Оставить комментарий / вопрос

phpjsHTMLCSSSQLПросто код
  Для того, чтобы оставить комментарий, пожалуйста, зарегистрируйтесь или авторизуйтесь на сайте.
Получайте новости блога по email или следите за мной в социальных сетях.
  • Владимир: и на третьей строке не хватает скобки ) закрывающей if :)

  • Миша: Добрый вечер! Рекомендую получить ID пользователя через функцию get_current_user_id().

  • Дмитрий: Миша, подскажите пожалуйста, я использую такой редирект, но он не срабатывает: add_action( 'template_redirect', funct...

  • Миша: Ну как не определена - это аргумент функции. Или я просто вас не до конца понимаю.

  • Артем: Ага, понял. Вот только почему $args? Она же нигде не определена, по логике должна быть переменная $true_field_params или...