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] => [email protected]
			[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 (рядок)

Запит на пошук користувачів. Пошук іде точного входження. Коли потрібно шукати підрядок, використовуйте у запиті * . Наприклад, якщо потрібно знайти користувача з ім’ям Іван Вікторович , то запит буде виглядати так: Іван Вікторович чи Іван* чи *Вікторович чи *Віктор*

Якщо параметр 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

Приклади

#1 Використання поля ‘search’ (пошук користувачів)

Цей приклад знайде і виведе на екран всіх користувачів, у яких ім’я, ID або email дорівнює “john”.

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

#2 Список 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>

#3 Знак `*`пошуку можна використовувати до або після запиту

Знак замінює будь-яку кількість символів. Наприклад, щоб знайти всіх користувачів у яких ID, ім’я або email починається з “jo”, використовуємо такий код:

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

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

Якщо поставити *на початок ( *jo), ми отримаємо користувачів, що закінчуються на jo.

#4 Отримаємо всі email адміністраторів сайту

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

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

/* $emails
Array
(
	[0] => [email protected]
	[1] => [email protected]
)
*/

нотатки

Дивіться: WP_User_Query

список змін

З версії 3.1.0

Введено.

Код `get_users() get users` ^{WP 6.0.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();
}

get_users() │ WP 3.1.0

Повертає

Шаблон використання

Використання

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

Приклади

#1 Використання поля ‘search’ (пошук користувачів)

#2 Список email всіх передплатників сайту мережі з ID 1:

#3 Знак *пошуку можна використовувати до або після запиту

#4 Отримаємо всі email адміністраторів сайту

нотатки

список змін

Код get_users() get users WP 6.0.2

Зв’язані функції

Користувачі (_user)

Решта

Залишити відповідь Скасувати коментар

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

#3 Знак `*`пошуку можна використовувати до або після запиту

Код `get_users() get users` ^{WP 6.0.2}