| [ Index ] |
PHP Cross Reference of WordPress |
[Source view] [Print] [Project Stats]
Core User API
| File Size: | 4938 lines (168 kb) |
| Included or required: | 0 times |
| Referenced: | 0 times |
| Includes or requires: | 1 file wp-includes/class-phpass.php |
| 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. return: WP_User|WP_Error WP_User on success, WP_Error on failure. param: array $credentials Optional. User info in order to sign on. param: string|bool $secure_cookie Optional. Whether to use secure cookie. since: 2.5.0 |
| wp_authenticate_username_password( $user, $username, $password ) X-Ref |
| Authenticates a user, confirming the username and password are valid. return: WP_User|WP_Error WP_User on success, WP_Error on failure. 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. since: 2.8.0 |
| wp_authenticate_email_password( $user, $email, $password ) X-Ref |
| Authenticates a user using the email and password. return: WP_User|WP_Error WP_User on success, WP_Error on failure. 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. since: 4.5.0 |
| wp_authenticate_cookie( $user, $username, $password ) X-Ref |
| Authenticates the user using the WordPress auth cookie. return: WP_User|WP_Error WP_User on success, WP_Error on failure. 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. since: 2.8.0 |
| wp_authenticate_application_password( $input_user, $username, $password ) X-Ref |
| Authenticates the user using an application password. return: WP_User|WP_Error|null WP_User on success, WP_Error on failure, null if param: WP_User|WP_Error|null $input_user WP_User or WP_Error object if a previous param: string $username Username for authentication. param: string $password Password for authentication. since: 5.6.0 |
| wp_validate_application_password( $input_user ) X-Ref |
| Validates the application password credentials passed via Basic Authentication. return: int|false The authenticated user ID if successful, false otherwise. param: int|false $input_user User ID if one has been determined, false otherwise. since: 5.6.0 |
| wp_authenticate_spam_check( $user ) X-Ref |
| For Multisite blogs, checks if the authenticated user has been marked as a spammer, or if the user's primary blog has been marked as spam. return: WP_User|WP_Error WP_User on success, WP_Error if the user is considered a spammer. param: WP_User|WP_Error|null $user WP_User or WP_Error object from a previous callback. Default null. since: 3.7.0 |
| 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. return: int|false User ID if validated, false otherwise. If a user ID from param: int|false $user_id The user ID (or false) as received from since: 3.9.0 |
| count_user_posts( $userid, $post_type = 'post', $public_only = false ) X-Ref |
| Gets the number of posts a user has written. return: string Number of posts the user has written in this post type. 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. since: 3.0.0 since: 4.1.0 Added `$post_type` argument. since: 4.3.0 Added `$public_only` argument. Added the ability to pass an array |
| count_many_users_posts( $users, $post_type = 'post', $public_only = false ) X-Ref |
| Gets the number of posts written by a list of users. return: string[] Amount of posts each user has written, as strings, keyed by user ID. param: int[] $users Array of user IDs. param: string|string[] $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. since: 3.0.0 |
| get_current_user_id() X-Ref |
| Gets the current user's ID. return: int The current user's ID, or 0 if no user is logged in. since: MU (3.0.0) |
| get_user_option( $option, $user = 0, $deprecated = '' ) X-Ref |
| Retrieves 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. return: mixed User option value on success, false on failure. 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. since: 2.0.0 |
| update_user_option( $user_id, $option_name, $newvalue, $global = false ) X-Ref |
| Updates 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. return: int|bool User meta ID if the option didn't exist, true on successful update, 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. since: 2.0.0 |
| delete_user_option( $user_id, $option_name, $global = false ) X-Ref |
| Deletes 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. return: bool True on success, false on failure. 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. since: 3.0.0 |
| get_users( $args = array() X-Ref |
| Retrieves list of users matching criteria. return: array List of users. param: array $args Optional. Arguments to retrieve users. See WP_User_Query::prepare_query() since: 3.1.0 |
| wp_list_users( $args = array() X-Ref |
| Lists all the users of the site, with several options available. return: string|null The output if echo is false. Otherwise null. param: string|array $args { since: 5.9.0 |
| get_blogs_of_user( $user_id, $all = false ) X-Ref |
| Gets the sites a user belongs to. return: object[] A list of the user's sites. An empty array if the user doesn't exist param: int $user_id User ID param: bool $all Whether to retrieve all sites, or only sites that are not since: 3.0.0 since: 4.7.0 Converted to use `get_sites()`. |
| is_user_member_of_blog( $user_id = 0, $blog_id = 0 ) X-Ref |
| Finds out whether a user is a member of a given blog. return: bool 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. since: MU (3.0.0) |
| add_user_meta( $user_id, $meta_key, $meta_value, $unique = false ) X-Ref |
| Adds meta data to a user. return: int|false Meta ID on success, false on failure. param: int $user_id User ID. param: string $meta_key Metadata name. param: mixed $meta_value Metadata value. Must be serializable if non-scalar. param: bool $unique Optional. Whether the same key should not be added. since: 3.0.0 |
| delete_user_meta( $user_id, $meta_key, $meta_value = '' ) X-Ref |
| Removes 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. return: bool True on success, false on failure. param: int $user_id User ID param: string $meta_key Metadata name. param: mixed $meta_value Optional. Metadata value. If provided, since: 3.0.0 |
| get_user_meta( $user_id, $key = '', $single = false ) X-Ref |
| Retrieves user meta field for a user. return: mixed An array of values if `$single` is false. param: int $user_id User ID. param: string $key Optional. The meta key to retrieve. By default, param: bool $single Optional. Whether to return a single value. since: 3.0.0 |
| update_user_meta( $user_id, $meta_key, $meta_value, $prev_value = '' ) X-Ref |
| Updates 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. return: int|bool Meta ID if the key didn't exist, true on successful update, param: int $user_id User ID. param: string $meta_key Metadata key. param: mixed $meta_value Metadata value. Must be serializable if non-scalar. param: mixed $prev_value Optional. Previous value to check before updating. since: 3.0.0 |
| count_users( $strategy = 'time', $site_id = null ) X-Ref |
| Counts 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. return: array { 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. since: 3.0.0 since: 4.4.0 The number of users with no role is now included in the `none` element. since: 4.9.0 The `$site_id` parameter was added to support multisite. |
| get_user_count( $network_id = null ) X-Ref |
| Returns the number of active users in your installation. Note that on a large site the count may be cached and only updated twice daily. return: int Number of active users on the network. param: int|null $network_id ID of the network. Defaults to the current network. since: MU (3.0.0) since: 4.8.0 The `$network_id` parameter has been added. since: 6.0.0 Moved to wp-includes/user.php. |
| wp_maybe_update_user_counts( $network_id = null ) X-Ref |
| Updates the total count of users on the site if live user counting is enabled. return: bool Whether the update was successful. param: int|null $network_id ID of the network. Defaults to the current network. since: 6.0.0 |
| wp_update_user_counts( $network_id = null ) X-Ref |
| Updates the total count of users on the site. return: bool Whether the update was successful. param: int|null $network_id ID of the network. Defaults to the current network. since: 6.0.0 |
| wp_schedule_update_user_counts() X-Ref |
| Schedules a recurring recalculation of the total count of users. since: 6.0.0 |
| wp_is_large_user_count( $network_id = null ) X-Ref |
| Determines whether the site has a large number of users. The default criteria for a large site is more than 10,000 users. return: bool Whether the site has a large number of users. param: int|null $network_id ID of the network. Defaults to the current network. since: 6.0.0 |
| setup_userdata( $for_user_id = 0 ) X-Ref |
| Sets 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. Default 0. since: 2.0.4 |
| wp_dropdown_users( $args = '' ) X-Ref |
| Creates 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: return: string HTML dropdown list of users. param: array|string $args { since: 2.3.0 since: 4.5.0 Added the 'display_name_with_login' value for 'show'. since: 4.7.0 Added the `$role`, `$role__in`, and `$role__not_in` parameters. |
| sanitize_user_field( $field, $value, $user_id, $context ) X-Ref |
| Sanitizes 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. return: mixed Sanitized value. 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', since: 2.3.0 |
| update_user_caches( $user ) X-Ref |
| Updates all user caches. return: void|false Void on success, false on failure. param: object|WP_User $user User object or database row to be cached since: 3.0.0 |
| clean_user_cache( $user ) X-Ref |
| Cleans all user caches. param: WP_User|int $user User object or ID to be cleaned from the cache since: 3.0.0 since: 4.4.0 'clean_user_cache' action was added. since: 5.8.0 Refreshes the global user instance if cleaning the user cache for the current user. |
| 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. return: int|false The user ID on success, false on failure. param: string $username The username to check for existence. since: 2.0.0 |
| 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. return: int|false The user ID on success, false on failure. param: string $email The email to check for existence. since: 2.1.0 |
| validate_username( $username ) X-Ref |
| Checks whether a username is valid. return: bool Whether username given is valid. param: string $username Username. since: 2.0.1 since: 4.4.0 Empty sanitized usernames are now considered invalid. |
| wp_insert_user( $userdata ) X-Ref |
| Inserts 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', 'user_activation_key', 'spam', 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. return: int|WP_Error The newly created user's ID or a WP_Error object if the user could not param: array|object|WP_User $userdata { since: 2.0.0 since: 3.6.0 The `aim`, `jabber`, and `yim` fields were removed as default user contact since: 4.7.0 The `locale` field can be passed to `$userdata`. since: 5.3.0 The `user_activation_key` field can be passed to `$userdata`. since: 5.3.0 The `spam` field can be passed to `$userdata` (Multisite only). since: 5.9.0 The `meta_input` field can be passed to `$userdata` to allow addition of user meta data. |
| wp_update_user( $userdata ) X-Ref |
| Updates 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. return: int|WP_Error The updated user's ID or a WP_Error object if the user could not be updated. param: array|object|WP_User $userdata An array of user data or a user object of type stdClass or WP_User. since: 2.0.0 |
| wp_create_user( $username, $password, $email = '' ) X-Ref |
| Provides 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. return: int|WP_Error The newly created user's ID or a WP_Error object if the user could not param: string $username The user's username. param: string $password The user's password. param: string $email Optional. The user's email. Default empty. since: 2.0.0 |
| _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. return: string[] List of user keys to be populated in wp_update_user(). param: WP_User $user WP_User instance. since: 3.3.0 |
| wp_get_user_contact_methods( $user = null ) X-Ref |
| Sets up the user contact methods. Default contact methods were removed in 3.6. A filter dictates contact methods. return: string[] Array of contact method labels keyed by contact method. param: WP_User|null $user Optional. WP_User object. since: 3.7.0 |
| _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. return: string[] Array of contact method labels keyed by contact method. param: WP_User|null $user Optional. WP_User object. Default null. since: 2.9.0 |
| wp_get_password_hint() X-Ref |
| Gets the text suggesting how to create strong passwords. return: string The password hint text. since: 4.1.0 |
| get_password_reset_key( $user ) X-Ref |
| Creates, stores, then returns a password reset key for user. return: string|WP_Error Password reset key on success. WP_Error on error. param: WP_User $user User to retrieve password reset key for. since: 4.4.0 |
| 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. return: WP_User|WP_Error WP_User object on success, WP_Error object for invalid or expired keys. param: string $key Hash to validate sending user's password. param: string $login The user login. since: 3.1.0 |
| retrieve_password( $user_login = null ) X-Ref |
| Handles sending a password retrieval email to a user. return: true|WP_Error True when finished, WP_Error object on error. param: string $user_login Optional. Username to send a password retrieval email for. since: 2.5.0 since: 5.7.0 Added `$user_login` parameter. |
| 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 since: 2.5.0 |
| register_new_user( $user_login, $user_email ) X-Ref |
| Handles registering a new user. return: int|WP_Error Either user's ID or error on failure. param: string $user_login User's username for logging in param: string $user_email User's email address to send password and add since: 2.5.0 |
| 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' since: 4.4.0 since: 4.6.0 Converted the `$notify` parameter to accept 'user' for sending |
| wp_get_session_token() X-Ref |
| Retrieves the current session token from the logged_in cookie. return: string Token. since: 4.0.0 |
| wp_get_all_sessions() X-Ref |
| Retrieves a list of sessions for the current user. return: array Array of sessions. since: 4.0.0 |
| wp_destroy_current_session() X-Ref |
| Removes the current session token from the database. since: 4.0.0 |
| wp_destroy_other_sessions() X-Ref |
| Removes all but the current session token for the current user for the database. since: 4.0.0 |
| wp_destroy_all_sessions() X-Ref |
| Removes all session tokens for the current user from the database. since: 4.0.0 |
| wp_get_users_with_no_role( $site_id = null ) X-Ref |
| Gets the user IDs of all users with no role on this site. return: string[] Array of user IDs as strings. param: int|null $site_id Optional. The site ID to get users with no role for. Defaults to the current site. since: 4.4.0 since: 4.9.0 The `$site_id` parameter was added to support multisite. |
| _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. since: 4.5.0 |
| send_confirmation_on_profile_email() X-Ref |
| Sends a confirmation request email when a change of user email address is attempted. since: 3.0.0 since: 4.9.0 This function was moved from wp-admin/includes/ms.php so it's no longer Multisite specific. |
| new_user_email_admin_notice() X-Ref |
| Adds an admin notice alerting the user to check for confirmation request email after email address change. since: 3.0.0 since: 4.9.0 This function was moved from wp-admin/includes/ms.php so it's no longer Multisite specific. |
| _wp_privacy_action_request_types() X-Ref |
| Gets all personal data request types. return: array List of core privacy action types. since: 4.9.6 |
| wp_register_user_personal_data_exporter( $exporters ) X-Ref |
| Registers the personal data exporter for users. return: array An array of personal data exporters. param: array $exporters An array of personal data exporters. since: 4.9.6 |
| 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. return: array An array of personal data. param: string $email_address The user's email address. since: 4.9.6 since: 5.4.0 Added 'Community Events Location' group to the export data. since: 5.4.0 Added 'Session Tokens' group to the export data. |
| _wp_privacy_account_request_confirmed( $request_id ) X-Ref |
| No description |
| _wp_privacy_send_request_confirmation_notification( $request_id ) X-Ref |
| Notifies 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. since: 4.9.6 |
| _wp_privacy_send_erasure_fulfillment_notification( $request_id ) X-Ref |
| Notifies 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. since: 4.9.6 |
| _wp_privacy_account_request_confirmed_message( $request_id ) X-Ref |
| Returns request confirmation message HTML. return: string The confirmation message. param: int $request_id The request ID being confirmed. since: 4.9.6 |
| wp_create_user_request( $email_address = '', $action_name = '', $request_data = array() X-Ref |
| Creates and logs 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. return: int|WP_Error Returns the request ID if successful, or a WP_Error object on failure. param: string $email_address User email address. This can be the address of a registered 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 param: string $status Optional request status (pending or confirmed). Default 'pending'. since: 4.9.6 since: 5.7.0 Added the `$status` parameter. |
| wp_user_request_action_description( $action_name ) X-Ref |
| Gets action description from the name and return a string. return: string Human readable action name. param: string $action_name Action name of the request. since: 4.9.6 |
| 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. return: true|WP_Error True on success, `WP_Error` on failure. param: string $request_id ID of the request created via wp_create_user_request(). since: 4.9.6 |
| 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. return: string Confirmation key. param: int $request_id Request ID. since: 4.9.6 |
| wp_validate_user_request_key( $request_id, $key ) X-Ref |
| Validates a user request by comparing the key with the request's key. return: true|WP_Error True on success, WP_Error on failure. param: string $request_id ID of the request being confirmed. param: string $key Provided key to validate. since: 4.9.6 |
| wp_get_user_request( $request_id ) X-Ref |
| Returns the user request object for the specified request ID. return: WP_User_Request|false param: int $request_id The ID of the user request. since: 4.9.6 |
| wp_is_application_passwords_supported() X-Ref |
| Checks if Application Passwords is supported. Application Passwords is supported only by sites using SSL or local environments but may be made available using the {@see 'wp_is_application_passwords_available'} filter. return: bool since: 5.9.0 |
| wp_is_application_passwords_available() X-Ref |
| Checks if Application Passwords is globally available. By default, Application Passwords is available to all sites using SSL or to local environments. Use the {@see 'wp_is_application_passwords_available'} filter to adjust its availability. return: bool since: 5.6.0 |
| wp_is_application_passwords_available_for_user( $user ) X-Ref |
| Checks if Application Passwords is available for a specific user. By default all users can use Application Passwords. Use {@see 'wp_is_application_passwords_available_for_user'} to restrict availability to certain users. return: bool param: int|WP_User $user The user to check. since: 5.6.0 |
| Generated: Thu Nov 21 01:00:03 2024 | Cross-referenced by PHPXref 0.7.1 |