WordPress.org

Ready to get started?Download WordPress

Codex

Attention Interested in functions, hooks, classes, or methods? Check out the new WordPress Code Reference!

Function Reference/get users

Contents

Description

Retrieves an array of users matching the criteria given in $args.

Usage

 <?php get_users$args ); ?> 

Parameters

<?php $args = array(
	'blog_id'      => $GLOBALS['blog_id'],
	'role'         => '',
	'meta_key'     => '',
	'meta_value'   => '',
	'meta_compare' => '',
	'meta_query'   => array(),
	'include'      => array(),
	'exclude'      => array(),
	'orderby'      => 'login',
	'order'        => 'ASC',
	'offset'       => '',
	'search'       => '',
	'number'       => '',
	'count_total'  => false,
	'fields'       => 'all',
	'who'          => ''
 ); ?>
  • blog_id - The current blog's ID, unless multisite is enabled and another ID is provided
  • role - Limit the returned authors to the role specified.
  • include - An array of IDs. Only users matching these IDs will be returned. Note that at present the include and exclude (below) arguments cannot be used together. See ticket #23228
  • exclude - An array of IDs. Users matching these IDs will not be returned, regardless of the other arguments. It will be ignored if the include argument is set.
  • meta_key - The meta_key in the wp_usermeta table for the meta_value to be returned. See get_userdata() for the possible meta keys.
  • meta_value - The value of the meta key.
  • meta_compare - Operator to test the 'meta_value'. Possible values are '!=', '>', '>=', '<', or '<='. Default value is '='.
  • meta_query - A WP_Meta_Query.
  • orderby - Sort by 'ID', 'login', 'nicename', 'email', 'url', 'registered', 'display_name', 'post_count', or 'meta_value' (query must also contain a 'meta_key' - see WP_User_Query).
  • order - ASC (ascending) or DESC (descending).
  • offset - The first n users to be skipped in the returned array.
  • search - Use this argument to search users by email address, URL, ID or username (this does not currently include display name).
  • number - Limit the total number of users returned.
  • count_total - This is always false. To get a total count, call WP_User_Query directly instead. See here for usage.
  • fields - Which fields to include in the returned array. Default is 'all'. Pass an array of wp_users table fields to return an array of stdClass objects with only those fields.
  • who - If set to 'authors', only authors (user level greater than 0) will be returned.

Examples

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

The first 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>';
}

Returns

(Array) 
An array of IDs, stdClass objects, or WP_User objects, depending on the value of the 'fields' parameter.
  • If 'fields' is set to 'all' (default), or 'all_with_meta', it will return an array of WP_User objects.
  • If 'fields' is set to an array of wp_users table fields, it will return an array of stdClass objects with only those fields.
  • If 'fields' is set to any individual tt> wp_users</tt> table field, an array of IDs will be returned.

Notes

Changelog

Source Code

get_users() is located in wp-includes/user.php.

See also index of Function Reference and index of Template Tags.

Related