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' => ,
'include' => array(),
'exclude' => array(),
'orderby' => 'login',
'order' => 'ASC',
'offset' => ,
'search' => ,
'number' => ,
'count_total' => true,
'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.
  • exclude - An array of IDs. Users matching these IDs will not be returned, regardless of the other arguments.
  • 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 '='.
  • orderby - Sort by 'nicename', 'email', 'url', 'registered', 'display_name', or 'post_count'.
  • 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, username, or display name.
  • number - Limit the total number of users returned.
  • count_total - True by default.
  • fields - Which fields to include in the returned array. Default is "all". It appears one can also request 'all_with_meta'. Other Possible values appear to be those in the main user table (in 3.2.1). Previous documentations advised : fields are the same as those for meta_key. However use of meta_keys gives a SQL error.
  • who - If set to 'authors', only authors (user level greater than 0) will be returned.

Example 

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

Returns

array of 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

Changelog

Since: Version 3.1

Source Code

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

See also index of Function Reference and index of Template Tags.
Retrieved from "http://codex.wordpress.org/Function_Reference/get_users"

Codex Resources