Recently, I created this argument guide for WP_User_Query Class, similar to the existing WP_Query Class guide by Mark Luetke.

Some Basic Examples

Here's a basic usage example:

Here's a basic usage example for all users except authors:

Here's a basic usage example for all users except editors and administrators:

Modifying the Query

However, there is more to this than the basic query, just like WP_Query. Once the query has been prepared, you can easily access the query via pre_user_query hook. However, unlike WP_Query, by default, there is no way (no method like WP_Query::is_main_query()) to distinguish between user queries with WP_User_Query as one would do on pre_get_posts.

So for a complicated example: if we want to query users, control which query we change, and order (say) by the last name user meta field or some other user meta, we are stuck with two basic approaches to modifying the query and only the query you wish to modify.

Approach #1 (Not the best IMHO)

First, you could modify the query directly through the WP_User_Query object. Though the PHP docs claims that WP_User_Query::query() is a private function, it really isn't. So you can do something like this:

Please note the Caveat: This creates 2 queries and any use of this code should also use site transients.

Basically this code, makes one query, with the original arguments. Then we modify the query arguments in the object and the re-execute the query method, by-passing the sanitizing prepare method. Going this route could drastically hurt your site both in performance and simply breaking the site.

Side Note: $author_query = new WP_User_Query(); doesn't actually prepare or run the query. It creates an object that looks like this:

WP_User_Query Object
(
    [results] =>
    [total_users] => 0
    [query_fields] =>
    [query_from] =>
    [query_where] =>
    [query_orderby] =>
    [query_limit] =>
)

Approach #2 (The better approach)

Second (and by far the better way), you can add an identifier argument (here: query_id), which WordPress retains as a query_var.

WP_User_Query Public Methods

WP_User_Query has two declared public methods: WP_User_Query::get_results() and WP_User_Query::get_total().

In both of these public methods, they simply return a parameter. In essence, the following two examples are the same for getting/accessing the results of the query:
[php]<?php
$author_query = new WP_User_Query( $args );
$authors = $author_query->get_results();
[/php]
[php]<?php
$author_query = new WP_User_Query( $args );
$authors = $author_query->results;
[/php]

Likewise, the same is true for get_total() method. The following two examples are the same for getting the total number of users from the WP_User_Query:
[php]<?php
$author_query = new WP_User_Query( $args );
$total = $author_query->get_total();
[/php]
[php]<?php
$author_query = new WP_User_Query( $args );
$total_authors = $author_query->total_users;
[/php]

WP_User can be found in root/wp-includes/capabilities.php. The constructor takes 3 parameters: $id (int|string::ID|login), $name (string), and $blog_id (int).

You can instantiate a specific user using the class:
[php]<?php
$user = new WP_User( $id [, $name [, $blog_id ] ] );
?>
[/php]

For example:
[php]<?php
$user = new WP_User( 2 );
?>
[/php]

OR, you can get the current user:
[php]<?php
$current_user = wp_get_current_user();
?>
[/php]

While there are normal functions like (e.g., get_the_author_meta() which uses get_userdata() which uses get_user_by() which is new in 3.3.0 and uses WP_User). WP_User has three "magic methods":

1. WP_User::__isset( $key ), which is the same as WP_User::has_prop( $key ).
   Example:
   [php]<?php
   $user = new WP_User( $id );
   if ( $user->__isset( 'myfield' ) )
   // do something
   [/php]
2. WP_User::__get( $key ), which is the same as WP_User::get( $key ).
   Example:
   [php]<?php
   $user = new WP_User( $id );
   if ( $user->__isset( 'myfield' ) )
   $myfield = $user->__get( 'myfield' );
   [/php]
3. WP_User::__set( $key ).
   Example:
   [php]<?php
   $user = new WP_User( $id );
   if ( ! $user->__isset( 'myfield' ) )
   $myfield = $user->__set( 'myfield', $value );
   [/php]

Here are some other methods:

• *Get user data: $user->get_data_by( $field, $value ); // Available fields: 'id', 'slug', 'email' or 'login'
• **Check if user exists: $user->exists();
• *Retrieve the value of a property or meta key: $user->get();
• *Determine whether a property or meta key is set: $user->has_prop();
• Retrieve all the role capabilities merged with the individual capabilities: $user->get_role_caps();
• Add role to a user: $user->add_role( $role );
• Remove role from a user: $user->remove_role( $role );
• Set role for a user: $user->set_role( $role );
• Choose the maximum level the user has: $user->level_reduction( $max, $item );
• Update the maximum user level for the user: $user->update_user_level_from_caps();
• Add cap to a user: $user->add_cap( $cap, $grant );
• Remove cap from a user: $user->remove_cap( $cap );
• Remove all caps from a user: $user->remove_all_caps();
• Determine whether user has a cap: $user->has_cap( $cap, $grant );
• Set blog to operate on: $user->for_blog( $blog_id ); // $blog_id defaults to current blog

*NEW in 3.3
**NEW in 3.4

Here is the object:
[php]
WP_User Object
(
[data] => stdClass Object
(
[ID] => 1
[user_login] => myloginusername
[user_pass] => xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
[user_nicename] => My Nice Name
[user_email] => [email protected]
[user_url] =>
[user_registered] => 2011-07-15 01:16:18
[user_activation_key] =>
[user_status] => 0
[display_name] => My Display Name
)

[ID] => 1
[caps] => Array
(
[administrator] => 1
)

[cap_key] => wp_capabilities
[roles] => Array
(
[0] => administrator
)

[allcaps] => Array
(
[switch_themes] => 1
[edit_themes] => 1
[activate_plugins] => 1
[edit_plugins] => 1
[edit_users] => 1
[edit_files] => 1
[manage_options] => 1
[moderate_comments] => 1
[manage_categories] => 1
[manage_links] => 1
[upload_files] => 1
[import] => 1
[unfiltered_html] => 1
[edit_posts] => 1
[edit_others_posts] => 1
[edit_published_posts] => 1
[publish_posts] => 1
[edit_pages] => 1
[read] => 1
[level_10] => 1
[level_9] => 1
[level_8] => 1
[level_7] => 1
[level_6] => 1
[level_5] => 1
[level_4] => 1
[level_3] => 1
[level_2] => 1
[level_1] => 1
[level_0] => 1
[edit_others_pages] => 1
[edit_published_pages] => 1
[publish_pages] => 1
[delete_pages] => 1
[delete_others_pages] => 1
[delete_published_pages] => 1
[delete_posts] => 1
[delete_others_posts] => 1
[delete_published_posts] => 1
[delete_private_posts] => 1
[edit_private_posts] => 1
[read_private_posts] => 1
[delete_private_pages] => 1
[edit_private_pages] => 1
[read_private_pages] => 1
[delete_users] => 1
[create_users] => 1
[unfiltered_upload] => 1
[edit_dashboard] => 1
[update_plugins] => 1
[delete_plugins] => 1
[install_plugins] => 1
[update_themes] => 1
[install_themes] => 1
[update_core] => 1
[list_users] => 1
[remove_users] => 1
[add_users] => 1
[promote_users] => 1
[edit_theme_options] => 1
[delete_themes] => 1
[export] => 1
[administrator] => 1
)

[filter] =>
)
[/php]

After writing this, I updated the WordPress Codex accordingly, which was missing all the 3.3.0 & 3.4.0 information.