WordPress.org

Class Reference/WP User Query

Description

The WordPress User Query class allows querying the user database and deprecates the WP_User_Search class since Version 3.1.

Usage

<?php $codex_users = new WP_User_Query( parameters ) ?>

Parameters

The WP_User_Query constructor allows the following parameters

blog_id (int) - the blog id on a multisite environment. Defaults to the current blog id.
role (string) - the user's role.
meta_key (string) - .
meta_value (string) - .
meta_compare (string) - .
include (array) - .
exclude (array) - .
search (string) - .
orderby (string) - Defaults to login.
order (string) - Defaults to ASC (ascending order).
offset (int) - Offset the returned results (needed in pagination).
number (int) - The maximum returned number of results (needed in pagination).
count_total (boolean) - .
fields (all) - Which fields to return. Defaults to all. If all_with_meta, query returns an array of WP_User objects. Must pass an array to subset fields returned.
who (string) -

Return Values

Either an array of row objects with properties corresponding to the wp_users table column names specified in 'fields' or, if 'fields' equals 'all_with_meta', an array of WP_User objects.

The default value for 'fields' is 'all' which will return all columns of the wp_users table in an array of row objects.

Examples

List all blog editors:

$wp_user_search = new WP_User_Query( array( 'role' => 'editor' ) );
$editors = $wp_user_search->get_results();

List all blog editors, return WP_User objects:

$wp_user_search = new WP_User_Query( array( 'role' => 'editor', 'fields' => 'all_with_meta' ) );
$editors = $wp_user_search->get_results();

List all blog editors, return limited fields in resulting row objects:

$args = array();
$args[0] = 'user_login';
$args[1] = 'user_nicename';
$args[2] = 'user_email';
$args[3] = 'user_url';
$wp_user_search = new WP_User_Query( array( 'role' => 'editor', 'fields' => $args ) );
$editors = $wp_user_search->get_results();

Notes

Change Log

Since: 3.1.0

Source File

class and function WP_User_Query is located in wp-includes/user.php.

WordPress.org

Codex

Class Reference/WP User Query

Contents