[ Index ]

PHP Cross Reference of WordPress Trunk (Updated Daily)

title

Body

[close]

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

Core User API

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

Defines 63 functions

  wp_signon()
  wp_authenticate_username_password()
  wp_authenticate_email_password()
  wp_authenticate_cookie()
  wp_authenticate_spam_check()
  wp_validate_logged_in_cookie()
  count_user_posts()
  count_many_users_posts()
  get_current_user_id()
  get_user_option()
  update_user_option()
  delete_user_option()
  get_users()
  get_blogs_of_user()
  is_user_member_of_blog()
  add_user_meta()
  delete_user_meta()
  get_user_meta()
  update_user_meta()
  count_users()
  setup_userdata()
  wp_dropdown_users()
  sanitize_user_field()
  update_user_caches()
  clean_user_cache()
  username_exists()
  email_exists()
  validate_username()
  wp_insert_user()
  wp_update_user()
  wp_create_user()
  _get_additional_user_keys()
  wp_get_user_contact_methods()
  _wp_get_user_contactmethods()
  wp_get_password_hint()
  get_password_reset_key()
  check_password_reset_key()
  reset_password()
  register_new_user()
  wp_send_new_user_notifications()
  wp_get_session_token()
  wp_get_all_sessions()
  wp_destroy_current_session()
  wp_destroy_other_sessions()
  wp_destroy_all_sessions()
  wp_get_users_with_no_role()
  _wp_get_current_user()
  send_confirmation_on_profile_email()
  new_user_email_admin_notice()
  _wp_privacy_action_request_types()
  wp_register_user_personal_data_exporter()
  wp_user_personal_data_exporter()
  _wp_privacy_account_request_confirmed()
  _wp_privacy_send_request_confirmation_notification()
  _wp_privacy_send_erasure_fulfillment_notification()
  _wp_privacy_account_request_confirmed_message()
  wp_create_user_request()
  wp_user_request_action_description()
  wp_send_user_request()
  wp_generate_user_request_key()
  wp_validate_user_request_key()
  wp_get_user_request_data()
  __construct()

Functions
Functions that are not part of a class:

wp_signon( $credentials = array()   X-Ref
Authenticates and logs a user in 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.

Note: wp_signon() doesn't handle setting the current user. This means that if the
function is called before the {@see 'init'} hook is fired, is_user_logged_in() will
evaluate as false until that point. If is_user_logged_in() is needed in conjunction
with wp_signon(), wp_set_current_user() should be called explicitly.

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

wp_authenticate_username_password( $user, $username, $password )   X-Ref
Authenticate a user, confirming the username and password are valid.

param: WP_User|WP_Error|null $user     WP_User or WP_Error object from a previous callback. Default null.
param: string                $username Username for authentication.
param: string                $password Password for authentication.
return: WP_User|WP_Error WP_User on success, WP_Error on failure.

wp_authenticate_email_password( $user, $email, $password )   X-Ref
Authenticates a user using the email and password.

param: WP_User|WP_Error|null $user     WP_User or WP_Error object if a previous
param: string                $email    Email address for authentication.
param: string                $password Password for authentication.
return: WP_User|WP_Error WP_User on success, WP_Error on failure.

wp_authenticate_cookie( $user, $username, $password )   X-Ref
Authenticate the user using the WordPress auth cookie.

param: WP_User|WP_Error|null $user     WP_User or WP_Error object from a previous callback. Default null.
param: string                $username Username. If not empty, cancels the cookie authentication.
param: string                $password Password. If not empty, cancels the cookie authentication.
return: WP_User|WP_Error WP_User on success, WP_Error on failure.

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.

param: WP_User|WP_Error|null $user WP_User or WP_Error object from a previous callback. Default null.
return: WP_User|WP_Error WP_User on success, WP_Error if the user is considered a spammer.

wp_validate_logged_in_cookie( $user_id )   X-Ref
Validates the logged-in cookie.

Checks the logged-in cookie if the previous auth cookie could not be
validated and parsed.

This is a callback for the {@see 'determine_current_user'} filter, rather than API.

param: int|bool $user_id The user ID (or false) as received from the
return: int|false User ID if validated, false otherwise. If a user ID from

count_user_posts( $userid, $post_type = 'post', $public_only = false )   X-Ref
Number of posts user has written.

param: int          $userid      User ID.
param: array|string $post_type   Optional. Single post type or array of post types to count the number of posts for. Default 'post'.
param: bool         $public_only Optional. Whether to only return counts for public posts. Default false.
return: string Number of posts the user has written in this post type.

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|array $post_type   Optional. Single post type or array of post types 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, or 0 if no user is logged in.

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: string $deprecated Use get_option() to check for an option in the options table.
return: mixed User option value on success, false on failure.

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.
return: int|bool User meta ID if the option didn't exist, true on successful update,

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.
return: bool True on success, false on failure.

get_users( $args = array()   X-Ref
Retrieve list of users matching criteria.

param: array $args Optional. Arguments to retrieve users. See WP_User_Query::prepare_query().
return: array List of users.

get_blogs_of_user( $user_id, $all = false )   X-Ref
Get the sites a user belongs to.

param: int  $user_id User ID
param: bool $all     Whether to retrieve all sites, or only sites that are not
return: array A list of the user's sites. An empty array if the user doesn't exist

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
Adds meta data to a user.

param: int    $user_id    User ID.
param: string $meta_key   Metadata name.
param: mixed  $meta_value Metadata value.
param: bool   $unique     Optional. Whether the same key should not be added. Default false.
return: int|false 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 is true.

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: int|bool Meta ID if the key didn't exist, true on successful update, false on failure.

count_users( $strategy = 'time', $site_id = null )   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 Optional. The computational strategy to use when counting the users.
param: int|null $site_id  Optional. The site ID to count users for. Defaults to the current site.
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:

param: array|string $args {
return: string String of HTML content.

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: WP_User $user User object to be cached
return: bool|null Returns false on failure.

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
Determines whether the given username exists.

For more information on this and similar theme functions, check out
the {@link https://developer.wordpress.org/themes/basics/conditional-tags/
Conditional Tags} article in the Theme Developer Handbook.

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

email_exists( $email )   X-Ref
Determines whether the given email exists.

For more information on this and similar theme functions, check out
the {@link https://developer.wordpress.org/themes/basics/conditional-tags/
Conditional Tags} article in the Theme Developer Handbook.

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

validate_username( $username )   X-Ref
Checks whether a username is valid.

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

wp_insert_user( $userdata )   X-Ref
Insert a user into the database.

Most of the `$userdata` array fields have filters associated with the values. Exceptions are
'ID', 'rich_editing', 'syntax_highlighting', 'comment_shortcuts', 'admin_color', 'use_ssl',
'user_registered', and 'role'. 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.

param: array|object|WP_User $userdata {
return: int|WP_Error The newly created user's ID or a WP_Error object if the user could not

wp_update_user( $userdata )   X-Ref
Update a 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: array|object|WP_User $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 a 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    Optional. The user's email. Default empty.
return: int|WP_Error The newly created user's ID or a WP_Error object if the user could not

_get_additional_user_keys( $user )   X-Ref
Returns a list of meta keys to be (maybe) populated in wp_update_user().

The list of keys returned via this function are dependent on the presence
of those keys in the user meta data to be set.

param: WP_User $user WP_User instance.
return: array List of user keys to be populated in wp_update_user().

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.

Use wp_get_user_contact_methods() instead.

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

wp_get_password_hint()   X-Ref
Gets the text suggesting how to create strong passwords.

return: string The password hint text.

get_password_reset_key( $user )   X-Ref
Creates, stores, then returns a password reset key for user.

param: WP_User $user User to retrieve password reset key for.
return: string|WP_Error Password reset key on success. WP_Error on error.

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: WP_User $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.

wp_send_new_user_notifications( $user_id, $notify = 'both' )   X-Ref
Initiates email notifications related to the creation of new users.

Notifications are sent both to the site admin and to the newly created user.

param: int    $user_id ID of the newly created user.
param: string $notify  Optional. Type of notification that should happen. Accepts 'admin'

wp_get_session_token()   X-Ref
Retrieve the current session token from the logged_in cookie.

return: string Token.

wp_get_all_sessions()   X-Ref
Retrieve a list of sessions for the current user.

return: array Array of sessions.

wp_destroy_current_session()   X-Ref
Remove the current session token from the database.


wp_destroy_other_sessions()   X-Ref
Remove all but the current session token for the current user for the database.


wp_destroy_all_sessions()   X-Ref
Remove all session tokens for the current user from the database.


wp_get_users_with_no_role( $site_id = null )   X-Ref
Get the user IDs of all users with no role on this site.

param: int|null $site_id Optional. The site ID to get users with no role for. Defaults to the current site.
return: array Array of user IDs.

_wp_get_current_user()   X-Ref
Retrieves the current user object.

Will set the current user, if the current user is not set. The current user
will be set to the logged-in person. If no user is logged-in, then it will
set the current user to 0, which is invalid and won't have any permissions.

This function is used by the pluggable functions wp_get_current_user() and
get_currentuserinfo(), the latter of which is deprecated but used for backward
compatibility.

return: WP_User Current WP_User instance.

send_confirmation_on_profile_email()   X-Ref
Send a confirmation request email when a change of user email address is attempted.


new_user_email_admin_notice()   X-Ref
Adds an admin notice alerting the user to check for confirmation request email
after email address change.


_wp_privacy_action_request_types()   X-Ref
Get all user privacy request types.

return: array List of core privacy action types.

wp_register_user_personal_data_exporter( $exporters )   X-Ref
Registers the personal data exporter for users.

param: array $exporters  An array of personal data exporters.
return: array An array of personal data exporters.

wp_user_personal_data_exporter( $email_address )   X-Ref
Finds and exports personal data associated with an email address from the user and user_meta table.

param: string $email_address  The users email address.
return: array An array of personal data.

_wp_privacy_account_request_confirmed( $request_id )   X-Ref
Update log when privacy request is confirmed.

param: int $request_id ID of the request.

_wp_privacy_send_request_confirmation_notification( $request_id )   X-Ref
Notify the site administrator via email when a request is confirmed.

Without this, the admin would have to manually check the site to see if any
action was needed on their part yet.

param: int $request_id The ID of the request.

_wp_privacy_send_erasure_fulfillment_notification( $request_id )   X-Ref
Notify the user when their erasure request is fulfilled.

Without this, the user would never know if their data was actually erased.

param: int $request_id The privacy request post ID associated with this request.

_wp_privacy_account_request_confirmed_message( $request_id )   X-Ref
Return request confirmation message HTML.

param: int $request_id The request ID being confirmed.
return: string $message The confirmation message.

wp_create_user_request( $email_address = '', $action_name = '', $request_data = array()   X-Ref
Create and log a user request to perform a specific action.

Requests are stored inside a post type named `user_request` since they can apply to both
users on the site, or guests without a user account.

param: string $email_address User email address. This can be the address of a registered or non-registered user.
param: string $action_name   Name of the action that is being confirmed. Required.
param: array  $request_data  Misc data you want to send with the verification request and pass to the actions once the request is confirmed.
return: int|WP_Error Returns the request ID if successful, or a WP_Error object on failure.

wp_user_request_action_description( $action_name )   X-Ref
Get action description from the name and return a string.

param: string $action_name Action name of the request.
return: string Human readable action name.

wp_send_user_request( $request_id )   X-Ref
Send a confirmation request email to confirm an action.

If the request is not already pending, it will be updated.

param: string $request_id ID of the request created via wp_create_user_request().
return: bool|WP_Error True on success, `WP_Error` on failure.

wp_generate_user_request_key( $request_id )   X-Ref
Returns a confirmation key for a user action and stores the hashed version for future comparison.

param: int $request_id Request ID.
return: string Confirmation key.

wp_validate_user_request_key( $request_id, $key )   X-Ref
Validate a user request by comparing the key with the request's key.

param: string $request_id ID of the request being confirmed.
param: string $key        Provided key to validate.
return: bool|WP_Error WP_Error on failure, true on success.

wp_get_user_request_data( $request_id )   X-Ref
Return data about a user request.

param: int $request_id Request ID to get data about.
return: WP_User_Request|false

__construct( $post )   X-Ref
Constructor.

param: WP_Post|object $post Post object.



Generated: Sun Oct 21 08:20:01 2018 Cross-referenced by PHPXref 0.7