get_users() │ WP 3.1.0

Gets users according to the passed parameters.

No Hooks.

Returns

Array. Array of IDs, stdClass objects, WP_User{} objects, depending on the value of the ‘fields‘ parameter.

• If 'fields' => 'all' (default), or fields = all_with_meta, it will return an array of WP_User{} objects.

  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] => Rudkov Niko
  		)
  
  		[caps] => Array(
  			[subscriber] => 1
  		)
  
  		...
  	)
  	[1] => WP_User Object( ... )
  	[2] => WP_User Object( ... )
  )
  

• If 'fields' => [ 'user_nicename' ] (instead user_nicename you may pass any column name of wp_users table), it will return an array of stdClass objects with only those fields.

  Array (
  	[0] => stdClass Object (
  			[user_nicename] => rudkovskij-nikolaj
  		)
  
  	[1] => stdClass Object (
  			[user_nicename] => active-directory-auditing
  		)
  
  	[2] => stdClass Object (
  			[user_nicename] => adam-slavo
  		)
  )

• If 'fields' => 'ID' array of IDs will be returned.

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

Usage Template

$users = get_users( [
	'blog_id'      => $GLOBALS['blog_id'],
	'role'         => '',
	'role__in'     => array(),
	'role__not_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() // see WP_Date_Query
] );

foreach( $users as $user ){
	// Process
}

Usage

get_users( $args );

$args(array)

Arguments to retrieve users. See WP_User_Query::prepare_query() for more information on accepted arguments.
Default: array()

Arguments of the $args parameter

• blog_id (number)
• role (string/array)
• role__in (array)
• role__not_in (array)
• include (array)
• exclude (array)
• meta_key (string)
• meta_value (string)
• meta_compare (string)
• meta_query (array)
• orderby (string).
• order (string)
• offset (number)
• number (number)
• paged (number)
• search (string)
• search_columns (array)
• fields (string/array)
• who (string)
• has_published_posts (bool/array/string)
• date_query (array)
• count_total (bool).

blog_id(number)

The ID of the current blog. Used when enabling multisites.

role(string/array)

The role of the users you want to get. Specified as an array or as a string (several roles are listed separated by commas). The received user must have all of the specified roles.

role__in(array)

An array of names of the roles the user should get. The received user must have at least one of the specified roles.
Default: array()

role__not_in(array)

An array of names of the roles, whose users should be excluded from the result. If the user has a specified role, he will be excluded.
Default: array()

include(array)

An array of users IDs you want to get. Only those users will be fetched, regardless of other parameters that do not match this parameter.

exclude(array)

An array of user IDs to exclude from the result.

meta_key(string)

The name of the meta key the user must have in order to be selected.

meta_value(string)

The value of the meta_key. The users will be fetched if the value matches.

meta_compare(string)

A comparison operator for the meta_value parameter. Can be: =, !=, >, >=, <, LIKE, NOT LIKE, IN, NOT IN, BETWEEN, NOT BETWEEN, EXISTS, NOT EXISTS, REGEXP, NOT REGEXP, RLIKE.

For example, specifying here the operator !=, will retrieve all users who have a meta_key with a value not equal to meta_value.
Default: '='

meta_query(array)

An array of meta_key/meta_value data. Similar to WP_Query.

orderby(string).

How the resulting list of users shoul be sorted?
You can specify: include, nicename, email, url, registered, display_name, post_count, meta_value, meta_value_num, $meta_key (key of the query array from meta_query).

Note: post_count only works for posts with post type and does not work for arbitrary post types (true for WP 4.6 version). It's not easy to get around this, maybe this will change in the future, but for now you can do it like this:

Let the post type be called realty, then use a hook like this right before get_users() call.

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 );
};

// Your get_users() call !!!!!!!!!!!!!!

remove_action( 'pre_user_query', 'temp_replace' );

Default: 'user_login'

order(string)

Sort direction. ASC - from lesser to more (a-z). DESC - from more to less (z-a).

offset(number)

Offset from the beginning of the resulting list. If 5 is specified, the first 5 users in the resulting list will be skipped.

number(number)

The number of users you want to get.

paged(number)

Pagination page number. Used in conjunction with number parameter.
Default: 1

search(string)

Query to search for users. It searches by exact occurrence.

When you want to search for a substring, use * in the query. For example, if you want to search for a user named Alex Victorov, the query will look like this: Alex Victorov or Alex* or Victorov or Victor*.

If the parameter search_columns is not specified, then the search query will be analyzed and the search will be conducted in appropriate columns. By default, it searches in: email, URL, ID or username (the display name is not included in the search).

search_columns(array)

An array of column names in which to search for a query from the search parameter.
Can be: ID, login, nicename, email, url.

When you want to set a special set of columns, use the filter user_search_columns:

// $search_columns = apply_filters( 'user_search_columns', $search_columns, $search, $this );
add_filter( 'user_search_columns', function( $cols ){
	// change $cols

	return $cols;
} );

Default: array()

fields(string/array)

Which fields to include in the returned data about each user.

• all - all.
• all_with_meta - the user's metadata value will also be retrieved.
• ID, display_name, user_login, user_nicename, user_email, user_url, user_registered - fields from table wp_user - only specified data will be retrieved. These fields must be specified in the array, even if you want to get only one field, for example: [ 'user_email' ].

Default: all

who(string)

If you specify authors, only the authors will be shown.
Default: '' (all users)

has_published_posts(bool/array/string)

Specify the name of the post type or an array of names. Then it will retrieve users who have published posts of the specified type.

You can specify true, then there will be users with at least one published post of any public type.

date_query(array)

Query by date. See WP_Date_Query{}. Works with the user_registered column - when the user was registered.

count_total(bool).

For this function, the parameter cannot be changed and is always false. Used in WP_User_Query{} to create pagination.

Count how many users were found by the query.

Default: false

Examples

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

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

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

// Get all of the site administrators' emails
$users = get_users( [
	'role' => 'administrator',
	'fields' => ['user_email'],
] );

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

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

Add Your Own Example