Class: WP_User_Query

Core class used for querying users.


Properties

Name Type(s) Default Value Summary
query_vars array Query vars, after parsing
results array List of found user ids
total_users integer Total number of found users for the current query
meta_query WP_Meta_Query Metadata query container.
request string The SQL query used to fetch matching users.
compat_fields
query_fields
query_from
query_where
query_orderby
query_limit

Methods

WP_User_Query:: __call( string $name, array $arguments )

Make private/protected methods readable for backward compatibility. Since 4.0.0.

Arguments

Name Type(s) Default Value Description
$name string

Method to call.

$arguments array

Arguments to pass when calling.

Returns

mixed

Return value of the callback, false otherwise.


WP_User_Query:: __construct( null | string | array $query = null )

PHP5 constructor. Since 3.1.0.

Arguments

Name Type(s) Default Value Description
$query null | string | array

Optional. The query variables.


WP_User_Query:: __get( string $name )

Make private properties readable for backward compatibility. Since 4.0.0.

Arguments

Name Type(s) Default Value Description
$name string

Property to get.

Returns

mixed

Property.


WP_User_Query:: __isset( string $name )

Make private properties checkable for backward compatibility. Since 4.0.0.

Arguments

Name Type(s) Default Value Description
$name string

Property to check if set.

Returns

boolean

Whether the property is set.


WP_User_Query:: __set( string $name, mixed $value )

Make private properties settable for backward compatibility. Since 4.0.0.

Arguments

Name Type(s) Default Value Description
$name string

Property to check if set.

$value mixed

Property value.

Returns

mixed

Newly-set property.


WP_User_Query:: __unset( string $name )

Make private properties un-settable for backward compatibility. Since 4.0.0.

Arguments

Name Type(s) Default Value Description
$name string

Property to unset.


WP_User_Query:: fill_query_vars( array $args )

Fills in missing query variables with default values. Since 4.4.0.

Arguments

Name Type(s) Default Value Description
$args array

Query vars, as passed to WP_User_Query.

Returns

array

Complete query variables with undefined ones filled in with defaults.


WP_User_Query:: get( string $query_var )

Retrieve query variable. Since 3.5.0.

Arguments

Name Type(s) Default Value Description
$query_var string

Query variable key.

Returns

mixed


WP_User_Query:: get_results( )

Return the list of users. Since 3.1.0.

Returns

array

Array of results.


WP_User_Query:: get_search_sql( string $string, array $cols, boolean $wild = false )

Used internally to generate an SQL string for searching across multiple columns Since 3.1.0.

Arguments

Name Type(s) Default Value Description
$string string
$cols array
$wild boolean

Whether to allow wildcard searches. Default is false for Network Admin, true for single site. Single site allows leading and trailing wildcards, Network Admin only trailing.

Returns

string


WP_User_Query:: get_total( )

Return the total number of users for the current query. Since 3.1.0.

Returns

integer

Number of total users.


WP_User_Query:: parse_order( string $order )

Parse an 'order' query variable and cast it to ASC or DESC as necessary. Since 4.2.0.

Arguments

Name Type(s) Default Value Description
$order string

The 'order' query variable.

Returns

string

The sanitized 'order' query variable.


WP_User_Query:: parse_orderby( string $orderby )

Parse and sanitize 'orderby' keys passed to the user query. Since 4.2.0.

Arguments

Name Type(s) Default Value Description
$orderby string

Alias for the field to order by.

Returns

string

Value to used in the ORDER clause, if $orderby is valid.


WP_User_Query:: prepare_query( string | array $query = array() )

Prepare the query variables. Since 3.1.0. Since 4.1.0. Since 4.2.0. Since 4.3.0. Since 4.4.0. Since 4.7.0.

Arguments

Name Type(s) Default Value Description
$query string | array

{ Optional. Array or string of Query parameters.

@type int          $blog_id             The site ID. Default is the current site.
@type string|array $role                An array or a comma-separated list of role names that users must match
                                        to be included in results. Note that this is an inclusive list: users
                                        must match *each* role. Default empty.
@type array        $role__in            An array of role names. Matched users must have at least one of these
                                        roles. Default empty array.
@type array        $role__not_in        An array of role names to exclude. Users matching one or more of these
                                        roles will not be included in results. Default empty array.
@type string       $meta_key            User meta key. Default empty.
@type string       $meta_value          User meta value. Default empty.
@type string       $meta_compare        Comparison operator to test the `$meta_value`. Accepts '=', '!=',
                                        '>', '>=', '<', '<=', 'LIKE', 'NOT LIKE', 'IN', 'NOT IN',
                                        'BETWEEN', 'NOT BETWEEN', 'EXISTS', 'NOT EXISTS', 'REGEXP',
                                        'NOT REGEXP', or 'RLIKE'. Default '='.
@type array        $include             An array of user IDs to include. Default empty array.
@type array        $exclude             An array of user IDs to exclude. Default empty array.
@type string       $search              Search keyword. Searches for possible string matches on columns.
                                        When `$search_columns` is left empty, it tries to determine which
                                        column to search in based on search string. Default empty.
@type array        $search_columns      Array of column names to be searched. Accepts 'ID', 'login',
                                        'nicename', 'email', 'url'. Default empty array.
@type string|array $orderby             Field(s) to sort the retrieved users by. May be a single value,
                                        an array of values, or a multi-dimensional array with fields as
                                        keys and orders ('ASC' or 'DESC') as values. Accepted values are
                                        'ID', 'display_name' (or 'name'), 'include', 'user_login'
                                        (or 'login'), 'login__in', 'user_nicename' (or 'nicename'),
                                        'nicename__in', 'user_email (or 'email'), 'user_url' (or 'url'),
                                        'user_registered' (or 'registered'), 'post_count', 'meta_value',
                                        'meta_value_num', the value of `$meta_key`, or an array key of
                                        `$meta_query`. To use 'meta_value' or 'meta_value_num', `$meta_key`
                                        must be also be defined. Default 'user_login'.
@type string       $order               Designates ascending or descending order of users. Order values
                                        passed as part of an `$orderby` array take precedence over this
                                        parameter. Accepts 'ASC', 'DESC'. Default 'ASC'.
@type int          $offset              Number of users to offset in retrieved results. Can be used in
                                        conjunction with pagination. Default 0.
@type int          $number              Number of users to limit the query for. Can be used in
                                        conjunction with pagination. Value -1 (all) is supported, but
                                        should be used with caution on larger sites.
                                        Default empty (all users).
@type int          $paged               When used with number, defines the page of results to return.
                                        Default 1.
@type bool         $count_total         Whether to count the total number of users found. If pagination
                                        is not needed, setting this to false can improve performance.
                                        Default true.
@type string|array $fields              Which fields to return. Single or all fields (string), or array
                                        of fields. Accepts 'ID', 'display_name', 'user_login',
                                        'user_nicename', 'user_email', 'user_url', 'user_registered'.
                                        Use 'all' for all fields and 'all_with_meta' to include
                                        meta fields. Default 'all'.
@type string       $who                 Type of users to query. Accepts 'authors'.
                                        Default empty (all users).
@type bool|array   $has_published_posts Pass an array of post types to filter results to users who have
                                        published posts in those post types. `true` is an alias for all
                                        public post types.
@type string       $nicename            The user nicename. Default empty.
@type array        $nicename__in        An array of nicenames to include. Users matching one of these
                                        nicenames will be included in results. Default empty array.
@type array        $nicename__not_in    An array of nicenames to exclude. Users matching one of these
                                        nicenames will not be included in results. Default empty array.
@type string       $login               The user login. Default empty.
@type array        $login__in           An array of logins to include. Users matching one of these
                                        logins will be included in results. Default empty array.
@type array        $login__not_in       An array of logins to exclude. Users matching one of these
                                        logins will not be included in results. Default empty array.

}


WP_User_Query:: query( )

Execute the query, with the current variables. Since 3.1.0.


WP_User_Query:: set( string $query_var, mixed $value )

Set query variable. Since 3.5.0.

Arguments

Name Type(s) Default Value Description
$query_var string

Query variable key.

$value mixed

Query variable value.


WordPress Developer Newsletter

Stay informed of new chapter releases, important WordPress API updates and more.