WordPress.org

Ready to get started?Download WordPress

Codex

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

Difference between revisions of "Function Reference/get users"

(Fixed markup, see http://core.trac.wordpress.org/ticket/21343)
(Parameters)
Line 11: Line 11:
 
<pre>
 
<pre>
 
<?php $args = array(
 
<?php $args = array(
'blog_id' => $GLOBALS['blog_id'],
+
'blog_id' => $GLOBALS['blog_id'],
'role' => '',
+
'role' => '',
'meta_key' => '',
+
'meta_key' => '',
'meta_value' => '',
+
'meta_value' => '',
'meta_compare' => '',
+
'meta_compare' => '',
'include' => array(),
+
'include' => array(),
'exclude' => array(),
+
'exclude' => array(),
'orderby' => 'login',
+
'orderby' => 'login',
'order' => 'ASC',
+
'order' => 'ASC',
'offset' => '',
+
'offset' => '',
'search' => '',
+
'search' => '',
'number' => '',
+
'number' => '',
'count_total' => false,
+
'count_total' => false,
'fields' => 'all',
+
'fields' => 'all',
'who' => ''
+
'who' => ''
 
); ?>
 
); ?>
 
</pre>
 
</pre>

Revision as of 09:22, 25 July 2012

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' => 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.
  • 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 or username (this does not currently include display name).
  • number - Limit the total number of users returned.
  • count_total - False 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

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 user objects, except when fields= specifies a single Field to be returned, then an array of values is returned.

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

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.