get_users( array $args = array() )
Retrieve list of users matching criteria.
Description
See also
Parameters
- $args
-
(array) (Optional) Arguments to retrieve users. See WP_User_Query::prepare_query(). for more information on accepted arguments.
Default value: array()
Return
(array) List of users.
Source
File: 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();
}
Changelog
| Version | Description |
|---|---|
| 3.1.0 | Introduced. |
A basic example to display all subscribers in an unordered list.
<?php $blogusers = get_users( 'blog_id=1&orderby=nicename&role=subscriber' ); // Array of WP_User objects. foreach ( $blogusers as $user ) { echo '<span>' . esc_html( $user->user_email ) . '</span>'; }An example using the ‘search’ field.
<?php $blogusers = get_users( array( 'search' => 'john' ) ); // Array of WP_User objects. foreach ( $blogusers as $user ) { echo '<span>' . esc_html( $user->user_email ) . '</span>'; }This example will find and display all users that have a user name, ID, email of “john”. You can also do wild card search by adding an * before or after your search query. For example, to search for all users that start with “jo”, you would pass something like “jo*”.
The results will be all users whose user names, IDs, or emails that start with “jo”. The * can be placed before or after your search query. When placed before, the results will be all users that end in your query.
An example of querying by a specific field.
<?php $blogusers = get_users( array( 'fields' => array( 'display_name' ) ) ); // Array of stdClass objects. foreach ( $blogusers as $user ) { echo '<span>' . esc_html( $user->display_name ) . '</span>'; }An example of fetching users that match any one of an array of roles using
role__in.<?php $blogusers = get_users( [ 'role__in' => [ 'author', 'subscriber' ] ] ); // Array of WP_User objects. foreach ( $blogusers as $user ) { echo '<span>' . esc_html( $user->display_name ) . '</span>'; }