WordPress.org

Ready to get started?Download WordPress

Codex

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_Query style multiple meta_key/meta_value array. See WP_Query documentation for examples.
  • 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". If set to 'all_with_meta', all of the metadata for the users will be pulled into the cache. This can cause memory problems with large numbers of users, so it is recommended that you avoid that option unless you will be using lots of the users' meta fields. As of version 3.5, both 'all' and 'all_with_meta' will return WP_User objects, so you can easily access the user's meta data (formerly only 'all_with_meta' returned WP_User objects). Other possible values are the fields of the wp_users table.
  • who - If set to 'authors', only authors (user level greater than 0) will be returned.

Example

A basic example to display all subscribers in an unordered list.

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

An example using the 'search' field.

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

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 do this:

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

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.

Returns

Array of objects, except when fields specifies a single field to be returned, then an array of values is returned. If fields is set to all_with_meta, it will return an array of WP_User objects.

Example of Object return

[ID] => 1
[user_login] => admin
[user_pass] => $P$Bxudi6gJMk2GRt2ed3xvZ06c1BPZXi/
[user_nicename] => admin
[user_email] => admin@host.com
[user_url] => http://localhost/
[user_registered] => 2010-06-29 07:08:55
[user_activation_key] => 
[user_status] => 0
[display_name] => Richard Branson

Example for Array of Values when single Field specified

0 => Richard Branson
1 => Winston Churchill

Notes

Changelog

Source Code

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

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