Kama и campusboy1.5 года назад9 EN

get_users() │ WP 3.1.0

Получает пользователей в соответствии с переданными параметрами.

Работает на базе класса WP_User_Query{}

Основа для: wp_dropdown_users()

Хуков нет.

Возвращает

Массив. Массив IDs, объектов stdClass, WP_User{}, зависит от значения параметра fields.

  • Если 'fields' => 'all' (по умолчанию), или fields = all_with_meta, то будет возвращен массив объектов WP_User{}.

    Array (
	[0] => WP_User Object(
		[ID] => 30

		[data] => stdClass Object(
			[ID] => 29
			[user_login] => -
			[user_pass] => $P$B.ogb6EOfaEVc5hSif/XuAuE4RfSzV1
			[user_nicename] => rudkij-nik
			[user_email] => rijkola00@gmail.com
			[user_url] =>
			[user_registered] => 2020-11-08 13:45:04
			[user_activation_key] =>
			[user_status] => 1604843106
			[display_name] => Рудков Нико
		)

		[caps] => Array (
			[subscriber] => 1
		)

		...
	)
	[1] => WP_User Object( ... )
	[2] => WP_User Object( ... )
)

  • Если 'fields' => [ 'user_nicename' ] (вместо ``user_nicename'' вы можете передать любое имя столбца таблицы wp_users), то будет возвращен массив объектов stdClass, содержащий только эти поля.

    Array (
	[0] => stdClass Object (
			[user_nicename] => rudkovskij-nikolaj
		)

	[1] => stdClass Object (
			[user_nicename] => active-directory-auditing
		)

	[2] => stdClass Object (
			[user_nicename] => adam-slavo
		)
)

  • Если 'fields' => 'ID', будет возвращен массив идентификаторов.

    Array (
	[0] => 29
	[1] => 31
	[2] => 17
)

Шаблон использования

$users = get_users( [
	'blog_id'      => $GLOBALS['blog_id'],
	'role'         => '',
	'role__in'     => array(),
	'role__not_in' => array(),
	'capability'          => '',
	'capability__in'      => array(),
	'capability__not_in'  => array(),
	'login'        => '',
	'login__in'    => array(),
	'meta_key'     => '',
	'meta_value'   => '',
	'meta_compare' => '',
	'meta_query'   => array(),
	'include'      => array(),
	'exclude'      => array(),
	'orderby'      => 'login',
	'order'        => 'ASC',
	'offset'       => '',
	'search'       => '',
	'search_columns' => array(),
	'number'       => '',
	'paged'        => 1,
	'count_total'  => false,
	'fields'       => 'all',
	'who'          => '',
	'has_published_posts' => null,
	'date_query'   => array() // смотрите WP_Date_Query
] );

foreach( $users as $user ){
	// обрабатываем
}

Использование

$users = get_users( $args );
$args(массив)
Параметры по которым будут получены пользователи.
По умолчанию: дефолтные

Аргументы параметра $args

WP_User_Query::prepare_query() - полный список аргументов.

blog_id(число)
ID текущего блога. Используется при включении мультисайтов.
role(строка|массив)

Роли пользователей, которых нужно получить. Указывается в виде массива или строкой (несколько ролей перечисляются через запятую).

Получаемый юзер, должен иметь все из указанных ролей.

Список ролей по умолчанию:

administrator
editor
author
contributor
subscriber

Подробнее смотрите здесь.

role__in(массив)

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

Получаемый юзер, должен иметь хотя бы одну из указанных ролей.
По умолчанию: array()

role__not_in(массив)
Массив названий ролей, пользователей которых нужно исключить из результата. Если у юзера есть указанная роль он будет исключен.
По умолчанию: array()
capability(string|string[]) (WP 5.9)

Массив или список возможностей, разделенных запятыми, которым должны соответствовать пользователи, чтобы быть включенными в результат выборки.

Указанному тут списку пользователи должны соответствовать каждой возможности.

НЕ работает для возможностей, отсутствующих в базе данных или отфильтрованных через map_meta_cap.

Читайте подробнее об этой новинке: https://make.wordpress.org/core/2022/01/05/new-capability-queries-in-wordpress-5-9/

По умолчанию: ''

capability__in(string[]) (WP 5.9)

Массив имен возможностей. Соответствующие пользователи должны иметь хотя бы одну из этих возможностей.

НЕ работает для возможностей, отсутствующих в базе данных или отфильтрованных через map_meta_cap.

По умолчанию: array()

capability__not_in(string[]) (WP 5.9)

Массив имен возможностей для исключения. Пользователи, соответствующие одной или нескольким из этих возможностей, не будут включены в результат выборки.

НЕ работает для возможностей, отсутствующих в базе данных или отфильтрованных через map_meta_cap.

who(строка) (устарел)

Если указать authors, то будут показаны только авторы.

Этот аргумент устарел с WP 5.9, используйте новый аргумент capabilities или role. Подробнее читайте Capability Queries in WordPress 5.9.

По умолчанию: '' (все пользователи)

nicename(строка)
Никнейм пользователя.
По умолчанию: ''
nicename__in(строка[])
Массив Никнейм пользователей, которых нужно включить в выборку. Пользователи, совпадающие с одним из этих никнеймов, будут включены в результаты.
По умолчанию: array()
nicename__not_in(строка[])
Массив никнеймов для исключения. Пользователи, совпадающие с одним из этих никнеймов, не будут включены в результаты.
По умолчанию: array()
login(строка)
Логин пользователя.
По умолчанию: ''
login__in(строка[])
Массив логинов пользователей, которых нужно включить в выборку. Пользователи, совпадающие с одним из этих логинов, будут включены в результаты.
По умолчанию: array()
login__not_in(строка[])
Массив логинов для исключения. Пользователи, совпадающие с одним из этих логинов, не будут включены в результаты.
По умолчанию: array()
include(массив)
Массив ID пользователей, которых нужно получить. Будут получены только эти пользователи, независимо от других параметров, не соответствующих этому параметру.
exclude(массив)
Массив ID пользователей, которых нужно исключить из результата.
meta_key(строка)
Название ключа, который должен быть у пользователя, чтобы он попал в отбор.
meta_value(строка)
Значение ключа meta_key. Будут получены пользователи если совпадает значение.
meta_compare(строка)
Оператор сравнения для значения meta_value. Может быть: =, !=, >, >=, <, <=, LIKE, NOT LIKE, IN, NOT IN, BETWEEN, NOT BETWEEN, EXISTS, NOT EXISTS, REGEXP, NOT REGEXP, RLIKE. Например указав тут оператор !=, будут получены все пользователи у которых есть поле meta_key со значением не равным meta_value.
По умолчанию: '='
meta_query(массив)
Массив данных о meta_key/meta_value. По аналогии с WP_Query.
orderby(строка)

Как сортировать полученный список пользователей?
Можно указать: include, nicename, email, url, registered, display_name, post_count, meta_value, meta_value_num, $meta_key (ключ массива запроса из meta_query).

Заметка: post_count работает только для типа записи post и не работает для произвольных типов записей (справедливо для версии WP 4.6). Обойти это не просто, возможно в будущем это измениться, а пока можно сделать так:

Пусть тип записи называется realty, тогда используйте такой хук прямо перед get_users().

add_action('pre_user_query', 'temp_replace');
function temp_replace($query){
	$query->query_from = str_replace("post_type = 'post'", "post_type = 'realty'", $query->query_from );
};

// Ваш вызов get_users() !!!!!!!!!!!!!!

remove_action('pre_user_query', 'temp_replace');

По умолчанию: 'user_login'

order(строка)
Направление сортировки. ASC - от меньшего к большему (a-я). DESC - от большего к меньшему (я-а).
offset(число)
Отступ от начала полученного списка. Если указать 5, то 5 первых пользователей из полученного списка будут пропущены.
number(число)
Количество пользователей которых нужно получить.
paged(число)
Номер страницы пагинации. Используется в связке с параметром number.
По умолчанию: 1

Запрос для поиска пользователей. Поиск идет по точному вхождению. Когда нужно искать подстроку, используйте в запросе *. Например, если нужно найти пользователя с именем Иван Викторович, то запрос будет выглядеть так: Иван Викторович или Иван* или *Викторович или *Виктор*

Если параметр search_columns не указан, то будет проанализирован поисковой запрос и поиск будет проходить по подходящим колонкам. По умолчанию ищет в: e-mail, URL, ID или имя пользователя (отображаемое имя в поиске не участвует).

search_columns(массив)

Массив названий колонок в которых искать запрос из параметра search.
Может быть: ID, login, nicename, email, url.

Когда нужно установить особый сет колонок, используйте фильтр user_search_columns:

// $search_columns = apply_filters( 'user_search_columns', $search_columns, $search, $this );
add_filter( 'user_search_columns', function( $cols ){
	// изменяем $cols

	return $cols;
} );

По умолчанию: array()

fields(строка/массив)

Какие поля включить в возвращаемые данные о каждом пользователе.

  • ID
  • display_name
  • user_login
  • user_nicename
  • user_email
  • user_url
  • user_registered - поля из таблицы wp_user - будут получены только указанные данные. Эти поля нужно указывать в массиве, даже если нужно получить всего одно поле, например: [ 'user_email' ].
  • user_pass
  • user_activation_key
  • user_status
  • spam (only available on multisite installs)
  • deleted (only available on multisite installs)
  • all - все.
  • all_with_meta - будут получены еще и значение метаданных пользователя.

По умолчанию: 'all'

has_published_posts(логический/массив/строка)

Укажите название типа записи или массив названий. Тогда будут получены пользователи у которых есть опубликованные записи указанного типа.

Можно указать true, тогда будут получены пользователи у которых есть хоть одна опубликованная запись любого публичного типа.

date_query(массив)
Запрос по дате. Смотрите WP_Date_Query{}. Работает с колонкой user_registered - когда пользователь был зарегистрирован.
count_total(логический)

Для этой функции параметр нельзя изменить и он всегда равен false. Используется в WP_User_Query{} для создания пагинации.

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

По умолчанию: false

cache_results(true|false) (WP 6.3)
Нужно ли кэшировать результат.
По умолчанию: true

Примеры

1

#1 Получим все email администраторов сайта 

// получим email администраторов
$users = get_users( array(
	'role'   => 'administrator',
	'fields' => ['user_email'],
) );

$emails = wp_list_pluck( $users, 'user_email' );

/* $emails
Array
(
	[0] => mymail@bk.ru
	[1] => secondmail@list.ru
)
*/
0

#2 Использование поля 'search' (поиск пользователей)

Этот пример найдет и выведет на экран всех пользователей у которых имя, ID или email равен "john".

<ul>
<?php
	$blogusers = get_users('search=john');
	foreach ($blogusers as $user) {
		echo '<li>' . $user->user_email . '</li>';
	}
?>
</ul>
0

#3 Список email всех подписчиков сайта сети с ID 1: 

<ul>
<?php
	$blogusers = get_users( 'blog_id=1&orderby=nicename&role=subscriber' );
	foreach ( $blogusers as $user ) {
		echo '<li>' . $user->user_email . '</li>';
	}
?>
</ul>
0

#4 Знак * в поиске можно использовать до или после запроса

Знак заменяет любое количество любых символов. Например, чтобы найти всех пользователей у которых ID, имя или email начинается с "jo", используем такой код:

<ul>
	<?php
	$blogusers = get_users( 'search=jo*' );

	foreach ( $blogusers as $user ) {
		echo '<li>' . $user->user_email . '</li>';
	}
	?>
</ul>

Если поставить * в начало (*jo), то мы получим пользователей оканчивающихся на jo.

Заметки

Список изменений

С версии 3.1.0 Введена.

Код get_users() WP 6.7.2

wp-includes/user.php 
function get_users( $args = array() ) {

	$args                = wp_parse_args( $args );
	$args['count_total'] = false;

	$user_search = new WP_User_Query( $args );

	return (array) $user_search->get_results();
}

Пользователи (_user)

Остальное

9 комментариев
    Войти