WordPress Cross Reference

Class: WP_User_Query - X-Ref

WordPress User Query class.

__construct( $query = null ) X-Ref

PHP5 constructor

param: string|array $args The query variables
return: WP_User_Query

prepare_query() X-Ref

Prepare the query variables

query() X-Ref

Execute the query, with the current variables

get( $query_var ) X-Ref

Retrieve query variable.

param: string $query_var Query variable key.
return: mixed

set( $query_var, $value ) X-Ref

Set query variable.

param: string $query_var Query variable key.
param: mixed $value Query variable value.

get_search_sql( $string, $cols, $wild = false ) X-Ref

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

param: string $string
param: array $cols
param: bool $wild Whether to allow wildcard searches. Default is false for Network Admin, true for
return: string

get_results() X-Ref

Return the list of users

return: array

get_total() X-Ref

Return the total number of users for the current query

return: array

get_users( $args = array() X-Ref

Retrieve list of users matching criteria.

param: array $args Optional.
return: array List of users.

get_blogs_of_user( $user_id, $all = false ) X-Ref

Get the blogs a user belongs to.

param: int $user_id User ID
param: bool $all Whether to retrieve all blogs, or only blogs that are not marked as deleted, archived, or spam.
return: array A list of the user's blogs. An empty array if the user doesn't exist or belongs to no blogs.

is_user_member_of_blog( $user_id = 0, $blog_id = 0 ) X-Ref

Find out whether a user is a member of a given blog.

param: int $user_id Optional. The unique ID of the user. Defaults to the current user.
param: int $blog_id Optional. ID of the blog to check. Defaults to the current site.
return: bool

add_user_meta($user_id, $meta_key, $meta_value, $unique = false) X-Ref

Add meta data field to a user.

Post meta data is called "Custom Fields" on the Administration Screens.

param: int $user_id User ID.
param: string $meta_key Metadata name.
param: mixed $meta_value Metadata value.
param: bool $unique Optional, default is false. Whether the same key should not be added.
return: int|bool Meta ID on success, false on failure.

delete_user_meta($user_id, $meta_key, $meta_value = '') X-Ref

Remove metadata matching criteria from a user.

You can match based on the key, or key and value. Removing based on key and
value, will keep from removing duplicate metadata with the same key. It also
allows removing all metadata matching key, if needed.

param: int $user_id user ID
param: string $meta_key Metadata name.
param: mixed $meta_value Optional. Metadata value.
return: bool True on success, false on failure.

get_user_meta($user_id, $key = '', $single = false) X-Ref

Retrieve user meta field for a user.

param: int $user_id User ID.
param: string $key Optional. The meta key to retrieve. By default, returns data for all keys.
param: bool $single Whether to return a single value.
return: mixed Will be an array if $single is false. Will be value of meta data field if $single

update_user_meta($user_id, $meta_key, $meta_value, $prev_value = '') X-Ref

Update user meta field based on user ID.

Use the $prev_value parameter to differentiate between meta fields with the
same key and user ID.

If the meta field for the user does not exist, it will be added.

param: int $user_id User ID.
param: string $meta_key Metadata key.
param: mixed $meta_value Metadata value.
param: mixed $prev_value Optional. Previous value to check before removing.
return: bool True on success, false on failure.

count_users($strategy = 'time') X-Ref

Count number of users who have each of the user roles.

Assumes there are neither duplicated nor orphaned capabilities meta_values.
Assumes role names are unique phrases. Same assumption made by WP_User_Query::prepare_query()
Using $strategy = 'time' this is CPU-intensive and should handle around 10^7 users.
Using $strategy = 'memory' this is memory-intensive and should handle around 10^5 users, but see WP Bug #12257.

param: string $strategy 'time' or 'memory'
return: array Includes a grand total and an array of counts indexed by role strings.

setup_userdata($for_user_id = '') X-Ref

Set up global user vars.

Used by wp_set_current_user() for back compat. Might be deprecated in the future.

param: int $for_user_id Optional. User ID to set up global data.

wp_dropdown_users( $args = '' ) X-Ref

Create dropdown HTML content of users.

The content can either be displayed, which it is by default or retrieved by
setting the 'echo' argument. The 'include' and 'exclude' arguments do not
need to be used; all users will be displayed in that case. Only one can be
used, either 'include' or 'exclude', but not both.

The available arguments are as follows:
<ol>
<li>show_option_all - Text to show all and whether HTML option exists.</li>
<li>show_option_none - Text for show none and whether HTML option exists.</li>
<li>hide_if_only_one_author - Don't create the dropdown if there is only one user.</li>
<li>orderby - SQL order by clause for what order the users appear. Default is 'display_name'.</li>
<li>order - Default is 'ASC'. Can also be 'DESC'.</li>
<li>include - User IDs to include.</li>
<li>exclude - User IDs to exclude.</li>
<li>multi - Default is 'false'. Whether to skip the ID attribute on the 'select' element. A 'true' value is overridden when id argument is set.</li>
<li>show - Default is 'display_name'. User table column to display. If the selected item is empty then the user_login will be displayed in parentheses</li>
<li>echo - Default is '1'. Whether to display or retrieve content.</li>
<li>selected - Which User ID is selected.</li>
<li>include_selected - Always include the selected user ID in the dropdown. Default is false.</li>
<li>name - Default is 'user'. Name attribute of select element.</li>
<li>id - Default is the value of the 'name' parameter. ID attribute of select element.</li>
<li>class - Class attribute of select element.</li>
<li>blog_id - ID of blog (Multisite only). Defaults to ID of current blog.</li>
<li>who - Which users to query. Currently only 'authors' is supported. Default is all users.</li>
</ol>

param: string|array $args Optional. Override defaults.
return: string|null Null on display. String of HTML content on retrieve.

sanitize_user_field($field, $value, $user_id, $context) X-Ref

Sanitize user field based on context.

Possible context values are: 'raw', 'edit', 'db', 'display', 'attribute' and 'js'. The
'display' context is used by default. 'attribute' and 'js' contexts are treated like 'display'
when calling filters.

param: string $field The user Object field name.
param: mixed $value The user Object value.
param: int $user_id user ID.
param: string $context How to sanitize user fields. Looks for 'raw', 'edit', 'db', 'display',
return: mixed Sanitized value.

update_user_caches($user) X-Ref

Update all user caches

param: object $user User object to be cached

clean_user_cache( $user ) X-Ref

Clean all user caches

param: WP_User|int $user User object or ID to be cleaned from the cache

username_exists( $username ) X-Ref

Checks whether the given username exists.

param: string $username Username.
return: null|int The user's ID on success, and null on failure.

email_exists( $email ) X-Ref

Checks whether the given email exists.

param: string $email Email.
return: bool|int The user's ID on success, and false on failure.

validate_username( $username ) X-Ref

Checks whether an username is valid.

param: string $username Username.
return: bool Whether username given is valid

wp_insert_user( $userdata ) X-Ref

Insert an user into the database.

Most of the $userdata array fields have filters associated with the values.
The exceptions are 'rich_editing', 'role', 'jabber', 'aim', 'yim',
'user_registered', and 'ID'. The filters have the prefix 'pre_user_' followed
by the field name. An example using 'description' would have the filter
called, 'pre_user_description' that can be hooked into.

The $userdata array can contain the following fields:
'ID' - An integer that will be used for updating an existing user.
'user_pass' - A string that contains the plain text password for the user.
'user_login' - A string that contains the user's username for logging in.
'user_nicename' - A string that contains a URL-friendly name for the user.
The default is the user's username.
'user_url' - A string containing the user's URL for the user's web site.
'user_email' - A string containing the user's email address.
'display_name' - A string that will be shown on the site. Defaults to user's
username. It is likely that you will want to change this, for appearance.
'nickname' - The user's nickname, defaults to the user's username.
'first_name' - The user's first name.
'last_name' - The user's last name.
'description' - A string containing content about the user.
'rich_editing' - A string for whether to enable the rich editor. False
if not empty.
'user_registered' - The date the user registered. Format is 'Y-m-d H:i:s'.
'role' - A string used to set the user's role.
'jabber' - User's Jabber account.
'aim' - User's AOL IM account.
'yim' - User's Yahoo IM account.

param: mixed $userdata An array of user data or a user object of type stdClass or WP_User.
return: int|WP_Error The newly created user's ID or a WP_Error object if the user could not be created.

wp_update_user($userdata) X-Ref

Update an user in the database.

It is possible to update a user's password by specifying the 'user_pass'
value in the $userdata parameter array.

If current user's password is being updated, then the cookies will be
cleared.

param: mixed $userdata An array of user data or a user object of type stdClass or WP_User.
return: int|WP_Error The updated user's ID or a WP_Error object if the user could not be updated.

wp_create_user($username, $password, $email = '') X-Ref

A simpler way of inserting an user into the database.

Creates a new user with just the username, password, and email. For more
complex user creation use wp_insert_user() to specify more information.

param: string $username The user's username.
param: string $password The user's password.
param: string $email The user's email (optional).
return: int The new user's ID.

_get_additional_user_keys( $user ) X-Ref

Return a list of meta keys that wp_insert_user() is supposed to set.

param: object $user WP_User instance.
return: array

wp_get_user_contact_methods( $user = null ) X-Ref

Set up the user contact methods.

Default contact methods were removed in 3.6. A filter dictates contact methods.

param: WP_User $user Optional. WP_User object.
return: array Array of contact methods and their labels.

_wp_get_user_contactmethods( $user = null ) X-Ref

The old private function for setting up user contact methods.

check_password_reset_key($key, $login) X-Ref

Retrieves a user row based on password reset key and login

A key is considered 'expired' if it exactly matches the value of the
user_activation_key field, rather than being matched after going through the
hashing process. This field is now hashed; old values are no longer accepted
but have a different WP_Error code so good user feedback can be provided.

param: string $key Hash to validate sending user's password.
param: string $login The user login.
return: WP_User|WP_Error WP_User object on success, WP_Error object for invalid or expired keys.

reset_password( $user, $new_pass ) X-Ref

Handles resetting the user's password.

param: object $user The user
param: string $new_pass New password for the user in plaintext

register_new_user( $user_login, $user_email ) X-Ref

Handles registering a new user.

param: string $user_login User's username for logging in
param: string $user_email User's email address to send password and add
return: int|WP_Error Either user's ID or error on failure.

Functions

Functions that are not part of a class:

wp_signon( $credentials = '', $secure_cookie = '' ) X-Ref

Authenticate user with remember capability.

The credentials is an array that has 'user_login', 'user_password', and
'remember' indices. If the credentials is not given, then the log in form
will be assumed and used if set.

The various authentication cookies will be set by this function and will be
set for a longer period depending on if the 'remember' credential is set to
true.

param: array $credentials Optional. User info in order to sign on.
param: bool $secure_cookie Optional. Whether to use secure cookie.
return: object Either WP_Error on failure, or WP_User on success.

wp_authenticate_username_password($user, $username, $password) X-Ref

Authenticate the user using the username and password.

wp_authenticate_cookie($user, $username, $password) X-Ref

Authenticate the user using the WordPress auth cookie.

wp_authenticate_spam_check( $user ) X-Ref

For multisite blogs, check if the authenticated user has been marked as a
spammer, or if the user's primary blog has been marked as spam.

count_user_posts($userid) X-Ref

Number of posts user has written.

param: int $userid User ID.
return: int Amount of posts user has written.

count_many_users_posts( $users, $post_type = 'post', $public_only = false ) X-Ref

Number of posts written by a list of users.

param: array $users Array of user IDs.
param: string $post_type Optional. Post type to check. Defaults to post.
param: bool $public_only Optional. Only return counts for public posts. Defaults to false.
return: array Amount of posts each user has written.

get_current_user_id() X-Ref

Get the current user's ID

return: int The current user's ID

get_user_option( $option, $user = 0, $deprecated = '' ) X-Ref

Retrieve user option that can be either per Site or per Network.

If the user ID is not given, then the current user will be used instead. If
the user ID is given, then the user data will be retrieved. The filter for
the result, will also pass the original option name and finally the user data
object as the third parameter.

The option will first check for the per site name and then the per Network name.

param: string $option User option name.
param: int $user Optional. User ID.
param: bool $deprecated Use get_option() to check for an option in the options table.
return: mixed

update_user_option( $user_id, $option_name, $newvalue, $global = false ) X-Ref

Update user option with global blog capability.

User options are just like user metadata except that they have support for
global blog options. If the 'global' parameter is false, which it is by default
it will prepend the WordPress table prefix to the option name.

Deletes the user option if $newvalue is empty.

param: int $user_id User ID
param: string $option_name User option name.
param: mixed $newvalue User option value.
param: bool $global Optional. Whether option name is global or blog specific. Default false (blog specific).
return: unknown

delete_user_option( $user_id, $option_name, $global = false ) X-Ref

Delete user option with global blog capability.

User options are just like user metadata except that they have support for
global blog options. If the 'global' parameter is false, which it is by default
it will prepend the WordPress table prefix to the option name.

param: int $user_id User ID
param: string $option_name User option name.
param: bool $global Optional. Whether option name is global or blog specific. Default false (blog specific).
return: unknown

File Size:	1706 lines (53 kb)
Included or required:	0 times
Referenced:	0 times
Includes or requires:	1 file wp-includes/class-phpass.php

/wp-includes/ -> user.php (summary)

Defines 1 class

Defines 33 functions