get_users()
Gets users according to the passed parameters.
Works based on WP_User_Query{} class
No Hooks.
Returns
Array
. Array of IDs
, stdClass objects
, WP_User{} objects, depending on the value of the ‘fields‘ parameter.
-
If
'fields' => 'all'
(default), orfields = 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)
- 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 ameta_key
with a value not equal tometa_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 withpost
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 beforeget_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 namedAlex Victorov
, the query will look like this:Alex Victorov
orAlex*
orVictorov
orVictor*
.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 tablewp_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
#1 Print the e-mail list of all blog subscribers with 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>
#2 Example using the 'search' param
This example will find and display all users whose name, ID or email is "john".
<ul> <?php $blogusers = get_users( 'search=john' ); foreach ($blogusers as $user) { echo '<li>' . $user->user_email . '</li>'; } ?> </ul>
#3 You can also use the *
sign before or after the query to search.
The sign replaces any number of any characters. For example, to find all users whose ID, name or email starts with "jo", use this code:
<ul> <?php $blogusers = get_users( 'search=jo*' ); foreach ( $blogusers as $user ) { echo '<li>' . $user->user_email . '</li>'; } ?> </ul>
If we put jo
at the beginning (jo
), we get users ending on jo
.
#4 Get all the site administrators' emails
// 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] ) */
Notes
- See: WP_User_Query
Changelog
Since 3.1.0 | Introduced. |
get_users() get users code WP 6.1.1
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(); }