X-Git-Url: https://scripts.mit.edu/gitweb/autoinstalls/wordpress.git/blobdiff_plain/256a3b381f63716209b3527d0a14442ae570c283..0f684a09c03e547d3132bddc970cbeafcd1102f4:/wp-includes/user.php?ds=sidebyside diff --git a/wp-includes/user.php b/wp-includes/user.php index 3bc29e14..5a9dc466 100644 --- a/wp-includes/user.php +++ b/wp-includes/user.php @@ -3,6 +3,7 @@ * WordPress User API * * @package WordPress + * @subpackage Users */ /** @@ -20,9 +21,9 @@ * * @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. + * @return WP_User|WP_Error WP_User on success, WP_Error on failure. */ -function wp_signon( $credentials = '', $secure_cookie = '' ) { +function wp_signon( $credentials = array(), $secure_cookie = '' ) { if ( empty($credentials) ) { if ( ! empty($_POST['log']) ) $credentials['user_login'] = $_POST['log']; @@ -37,13 +38,40 @@ function wp_signon( $credentials = '', $secure_cookie = '' ) { else $credentials['remember'] = false; - // TODO do we deprecate the wp_authentication action? - do_action_ref_array('wp_authenticate', array(&$credentials['user_login'], &$credentials['user_password'])); + /** + * Fires before the user is authenticated. + * + * The variables passed to the callbacks are passed by reference, + * and can be modified by callback functions. + * + * @since 1.5.1 + * + * @todo Decide whether to deprecate the wp_authenticate action. + * + * @param string $user_login Username, passed by reference. + * @param string $user_password User password, passed by reference. + */ + do_action_ref_array( 'wp_authenticate', array( &$credentials['user_login'], &$credentials['user_password'] ) ); if ( '' === $secure_cookie ) $secure_cookie = is_ssl(); - $secure_cookie = apply_filters('secure_signon_cookie', $secure_cookie, $credentials); + /** + * Filter whether to use a secure sign-on cookie. + * + * @since 3.1.0 + * + * @param bool $secure_cookie Whether to use a secure sign-on cookie. + * @param array $credentials { + * Array of entered sign-on data. + * + * @type string $user_login Username. + * @type string $user_password Password entered. + * @type bool $remember Whether to 'remember' the user. Increases the time + * that the cookie will be kept. Default false. + * } + */ + $secure_cookie = apply_filters( 'secure_signon_cookie', $secure_cookie, $credentials ); global $auth_secure_cookie; // XXX ugly hack to pass this to wp_authenticate_cookie $auth_secure_cookie = $secure_cookie; @@ -61,16 +89,32 @@ function wp_signon( $credentials = '', $secure_cookie = '' ) { } wp_set_auth_cookie($user->ID, $credentials['remember'], $secure_cookie); - do_action('wp_login', $user->user_login, $user); + /** + * Fires after the user has successfully logged in. + * + * @since 1.5.0 + * + * @param string $user_login Username. + * @param WP_User $user WP_User object of the logged-in user. + */ + do_action( 'wp_login', $user->user_login, $user ); return $user; } /** * Authenticate the user using the username and password. + * + * @since 2.8.0 + * + * @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. */ -add_filter('authenticate', 'wp_authenticate_username_password', 20, 3); function wp_authenticate_username_password($user, $username, $password) { - if ( is_a($user, 'WP_User') ) { return $user; } + if ( is_a( $user, 'WP_User' ) ) { + return $user; + } if ( empty($username) || empty($password) ) { if ( is_wp_error( $user ) ) @@ -92,7 +136,16 @@ function wp_authenticate_username_password($user, $username, $password) { if ( !$user ) return new WP_Error( 'invalid_username', sprintf( __( 'ERROR: Invalid username. Lost your password?' ), wp_lostpassword_url() ) ); - $user = apply_filters('wp_authenticate_user', $user, $password); + /** + * Filter whether the given user can be authenticated with the provided $password. + * + * @since 2.5.0 + * + * @param WP_User|WP_Error $user WP_User or WP_Error object if a previous + * callback failed authentication. + * @param string $password Password to check against the user. + */ + $user = apply_filters( 'wp_authenticate_user', $user, $password ); if ( is_wp_error($user) ) return $user; @@ -105,9 +158,18 @@ function wp_authenticate_username_password($user, $username, $password) { /** * Authenticate the user using the WordPress auth cookie. + * + * @since 2.8.0 + * + * @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. */ function wp_authenticate_cookie($user, $username, $password) { - if ( is_a($user, 'WP_User') ) { return $user; } + if ( is_a( $user, 'WP_User' ) ) { + return $user; + } if ( empty($username) && empty($password) ) { $user_id = wp_validate_auth_cookie(); @@ -131,13 +193,24 @@ function wp_authenticate_cookie($user, $username, $password) { } /** - * For multisite blogs, check if the authenticated user has been marked as a + * 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. * * @since 3.7.0 + * + * @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. */ function wp_authenticate_spam_check( $user ) { if ( $user && is_a( $user, 'WP_User' ) && is_multisite() ) { + /** + * Filter whether the user has been marked as a spammer. + * + * @since 3.7.0 + * + * @param bool $spammed Whether the user is considered a spammer. + * @param WP_User $user User to check against. + */ $spammed = apply_filters( 'check_is_user_spammed', is_user_spammy(), $user ); if ( $spammed ) @@ -146,11 +219,39 @@ function wp_authenticate_spam_check( $user ) { return $user; } +/** + * Validate 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 determine_current_user filter, rather than API. + * + * @since 3.9.0 + * + * @param int|bool $user The user ID (or false) as received from the + * determine_current_user filter. + * @return int|bool User ID if validated, false otherwise. If a user ID from + * an earlier filter callback is received, that value is returned. + */ +function wp_validate_logged_in_cookie( $user_id ) { + if ( $user_id ) { + return $user_id; + } + + if ( is_blog_admin() || is_network_admin() || empty( $_COOKIE[LOGGED_IN_COOKIE] ) ) { + return false; + } + + return wp_validate_auth_cookie( $_COOKIE[LOGGED_IN_COOKIE], 'logged_in' ); +} + /** * Number of posts user has written. * * @since 3.0.0 - * @uses $wpdb WordPress database object for queries. + * + * @global wpdb $wpdb WordPress database object for queries. * * @param int $userid User ID. * @return int Amount of posts user has written. @@ -162,7 +263,15 @@ function count_user_posts($userid) { $count = $wpdb->get_var( "SELECT COUNT(*) FROM $wpdb->posts $where" ); - return apply_filters('get_usernumposts', $count, $userid); + /** + * Filter the number of posts a user has written. + * + * @since 2.7.0 + * + * @param int $count The user's post count. + * @param int $userid User ID. + */ + return apply_filters( 'get_usernumposts', $count, $userid ); } /** @@ -229,14 +338,13 @@ function get_current_user_id() { * The option will first check for the per site name and then the per Network name. * * @since 2.0.0 - * @uses $wpdb WordPress database object for queries. - * @uses apply_filters() Calls 'get_user_option_$option' hook with result, - * option parameter, and user data object. - * - * @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 + * + * @global wpdb $wpdb WordPress database object for queries. + * + * @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 User option value on success, false on failure. */ function get_user_option( $option, $user = 0, $deprecated = '' ) { global $wpdb; @@ -258,7 +366,18 @@ function get_user_option( $option, $user = 0, $deprecated = '' ) { else $result = false; - return apply_filters("get_user_option_{$option}", $result, $option, $user); + /** + * Filter a specific user option value. + * + * The dynamic portion of the hook name, $option, refers to the user option name. + * + * @since 2.5.0 + * + * @param mixed $result Value for the user's option. + * @param string $option Name of the option being retrieved. + * @param WP_User $user WP_User object of the user whose option is being retrieved. + */ + return apply_filters( "get_user_option_{$option}", $result, $option, $user ); } /** @@ -271,13 +390,16 @@ function get_user_option( $option, $user = 0, $deprecated = '' ) { * Deletes the user option if $newvalue is empty. * * @since 2.0.0 - * @uses $wpdb WordPress database object for queries * - * @param int $user_id User ID + * @global wpdb $wpdb WordPress database object for queries. + * + * @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 + * @param mixed $newvalue User option value. + * @param bool $global Optional. Whether option name is global or blog specific. + * Default false (blog specific). + * @return int|bool User meta ID if the option didn't exist, true on successful update, + * false on failure. */ function update_user_option( $user_id, $option_name, $newvalue, $global = false ) { global $wpdb; @@ -296,12 +418,14 @@ function update_user_option( $user_id, $option_name, $newvalue, $global = false * it will prepend the WordPress table prefix to the option name. * * @since 3.0.0 - * @uses $wpdb WordPress database object for queries * - * @param int $user_id User ID + * @global wpdb $wpdb WordPress database object for queries. + * + * @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 + * @param bool $global Optional. Whether option name is global or blog specific. + * Default false (blog specific). + * @return bool True on success, false on failure. */ function delete_user_option( $user_id, $option_name, $global = false ) { global $wpdb; @@ -353,15 +477,32 @@ class WP_User_Query { var $query_limit; /** - * PHP5 constructor + * PHP5 constructor. * * @since 3.1.0 * - * @param string|array $args The query variables + * @param string|array $args Optional. The query variables. * @return WP_User_Query */ function __construct( $query = null ) { - if ( !empty( $query ) ) { + if ( ! empty( $query ) ) { + $this->prepare_query( $query ); + $this->query(); + } + } + + /** + * Prepare the query variables. + * + * @since 3.1.0 + * + * @param string|array $args Optional. The query variables. + */ + function prepare_query( $query = array() ) { + global $wpdb; + + if ( empty( $this->query_vars ) || ! empty( $query ) ) { + $this->query_limit = null; $this->query_vars = wp_parse_args( $query, array( 'blog_id' => $GLOBALS['blog_id'], 'role' => '', @@ -380,20 +521,7 @@ class WP_User_Query { 'fields' => 'all', 'who' => '' ) ); - - $this->prepare_query(); - $this->query(); } - } - - /** - * Prepare the query variables - * - * @since 3.1.0 - * @access private - */ - function prepare_query() { - global $wpdb; $qv =& $this->query_vars; @@ -496,6 +624,18 @@ class WP_User_Query { $search_columns = array('user_login', 'user_nicename'); } + /** + * Filter the columns to search in a WP_User_Query search. + * + * The default columns depend on the search term, and include 'user_email', + * 'user_login', 'ID', 'user_url', and 'user_nicename'. + * + * @since 3.6.0 + * + * @param array $search_columns Array of column names to be searched. + * @param string $search Text being searched. + * @param WP_User_Query $this The current WP_User_Query instance. + */ $search_columns = apply_filters( 'user_search_columns', $search_columns, $search, $this ); $this->query_where .= $this->get_search_sql( $search, $search_columns, $wild ); @@ -525,7 +665,9 @@ class WP_User_Query { $cap_meta_query['compare'] = 'like'; } - $qv['meta_query'][] = $cap_meta_query; + if ( empty( $qv['meta_query'] ) || ! in_array( $cap_meta_query, $qv['meta_query'], true ) ) { + $qv['meta_query'][] = $cap_meta_query; + } } $meta_query = new WP_Meta_Query(); @@ -548,26 +690,50 @@ class WP_User_Query { $this->query_where .= " AND $wpdb->users.ID NOT IN ($ids)"; } + /** + * Fires after the WP_User_Query has been parsed, and before + * the query is executed. + * + * The passed WP_User_Query object contains SQL parts formed + * from parsing the given query. + * + * @since 3.1.0 + * + * @param WP_User_Query $this The current WP_User_Query instance, + * passed by reference. + */ do_action_ref_array( 'pre_user_query', array( &$this ) ); } /** - * Execute the query, with the current variables + * Execute the query, with the current variables. * * @since 3.1.0 - * @access private + * + * @global wpdb $wpdb WordPress database object for queries. */ function query() { global $wpdb; $qv =& $this->query_vars; + $query = "SELECT $this->query_fields $this->query_from $this->query_where $this->query_orderby $this->query_limit"; + if ( is_array( $qv['fields'] ) || 'all' == $qv['fields'] ) { - $this->results = $wpdb->get_results("SELECT $this->query_fields $this->query_from $this->query_where $this->query_orderby $this->query_limit"); + $this->results = $wpdb->get_results( $query ); } else { - $this->results = $wpdb->get_col("SELECT $this->query_fields $this->query_from $this->query_where $this->query_orderby $this->query_limit"); + $this->results = $wpdb->get_col( $query ); } + /** + * Filter SELECT FOUND_ROWS() query for the current WP_User_Query instance. + * + * @since 3.2.0 + * + * @global wpdb $wpdb WordPress database object. + * + * @param string $sql The SELECT FOUND_ROWS() query for the current WP_User_Query. + */ if ( isset( $qv['count_total'] ) && $qv['count_total'] ) $this->total_users = $wpdb->get_var( apply_filters( 'found_users_query', 'SELECT FOUND_ROWS()' ) ); @@ -647,24 +813,24 @@ class WP_User_Query { } /** - * Return the list of users + * Return the list of users. * * @since 3.1.0 * @access public * - * @return array + * @return array Array of results. */ function get_results() { return $this->results; } /** - * Return the total number of users for the current query + * Return the total number of users for the current query. * * @since 3.1.0 * @access public * - * @return array + * @return array Array of total users. */ function get_total() { return $this->total_users; @@ -675,10 +841,10 @@ class WP_User_Query { * Retrieve list of users matching criteria. * * @since 3.1.0 - * @uses $wpdb + * * @uses WP_User_Query See for default arguments and information. * - * @param array $args Optional. + * @param array $args Optional. Array of arguments. * @return array List of users. */ function get_users( $args = array() ) { @@ -696,9 +862,13 @@ function get_users( $args = array() ) { * * @since 3.0.0 * - * @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. + * @global wpdb $wpdb WordPress database object for queries. + * + * @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. */ function get_blogs_of_user( $user_id, $all = false ) { global $wpdb; @@ -776,6 +946,16 @@ function get_blogs_of_user( $user_id, $all = false ) { } } + /** + * Filter the list of blogs a user belongs to. + * + * @since MU + * + * @param array $blogs An array of blog objects belonging to the user. + * @param int $user_id User ID. + * @param bool $all Whether the returned blogs array should contain all blogs, including + * those marked 'deleted', 'archived', or 'spam'. Default false. + */ return apply_filters( 'get_blogs_of_user', $blogs, $user_id, $all ); } @@ -875,7 +1055,7 @@ function get_user_meta($user_id, $key = '', $single = false) { * @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. + * @return int|bool Meta ID if the key didn't exist, true on successful update, false on failure. */ function update_user_meta($user_id, $meta_key, $meta_value, $prev_value = '') { return update_metadata('user', $user_id, $meta_key, $meta_value, $prev_value); @@ -1033,9 +1213,12 @@ function setup_userdata($for_user_id = '') { * * * @since 2.3.0 - * @uses $wpdb WordPress database object for queries * - * @param string|array $args Optional. Override defaults. + * @global wpdb $wpdb WordPress database object for queries. + * + * @todo Hash-notate arguments array. + * + * @param string|array $args Optional. Array of user arguments. * @return string|null Null on display. String of HTML content on retrieve. */ function wp_dropdown_users( $args = '' ) { @@ -1095,7 +1278,14 @@ function wp_dropdown_users( $args = '' ) { $output .= ""; } - $output = apply_filters('wp_dropdown_users', $output); + /** + * Filter the wp_dropdown_users() HTML output. + * + * @since 2.3.0 + * + * @param string $output HTML output generated by wp_dropdown_users(). + */ + $output = apply_filters( 'wp_dropdown_users', $output ); if ( $echo ) echo $output; @@ -1111,12 +1301,6 @@ function wp_dropdown_users( $args = '' ) { * when calling filters. * * @since 2.3.0 - * @uses apply_filters() Calls 'edit_$field' passing $value and $user_id if $context == 'edit'. - * $field is prefixed with 'user_' if it isn't already. - * @uses apply_filters() Calls 'pre_$field' passing $value if $context == 'db'. $field is prefixed with - * 'user_' if it isn't already. - * @uses apply_filters() Calls '$field' passing $value, $user_id and $context if $context == anything - * other than 'raw', 'edit' and 'db'. $field is prefixed with 'user_' if it isn't already. * * @param string $field The user Object field name. * @param mixed $value The user Object value. @@ -1140,9 +1324,23 @@ function sanitize_user_field($field, $value, $user_id, $context) { if ( 'edit' == $context ) { if ( $prefixed ) { - $value = apply_filters("edit_{$field}", $value, $user_id); + + /** This filter is documented in wp-includes/post.php */ + $value = apply_filters( "edit_{$field}", $value, $user_id ); } else { - $value = apply_filters("edit_user_{$field}", $value, $user_id); + + /** + * Filter a user field value in the 'edit' context. + * + * The dynamic portion of the hook name, $field, refers to the prefixed user + * field being filtered, such as 'user_login', 'user_email', 'first_name', etc. + * + * @since 2.9.0 + * + * @param mixed $value Value of the prefixed user field. + * @param int $user_id User ID. + */ + $value = apply_filters( "edit_user_{$field}", $value, $user_id ); } if ( 'description' == $field ) @@ -1151,16 +1349,44 @@ function sanitize_user_field($field, $value, $user_id, $context) { $value = esc_attr($value); } else if ( 'db' == $context ) { if ( $prefixed ) { - $value = apply_filters("pre_{$field}", $value); + /** This filter is documented in wp-includes/post.php */ + $value = apply_filters( "pre_{$field}", $value ); } else { - $value = apply_filters("pre_user_{$field}", $value); + + /** + * Filter the value of a user field in the 'db' context. + * + * The dynamic portion of the hook name, $field, refers to the prefixed user + * field being filtered, such as 'user_login', 'user_email', 'first_name', etc. + * + * @since 2.9.0 + * + * @param mixed $value Value of the prefixed user field. + */ + $value = apply_filters( "pre_user_{$field}", $value ); } } else { // Use display filters by default. - if ( $prefixed ) - $value = apply_filters($field, $value, $user_id, $context); - else - $value = apply_filters("user_{$field}", $value, $user_id, $context); + if ( $prefixed ) { + + /** This filter is documented in wp-includes/post.php */ + $value = apply_filters( $field, $value, $user_id, $context ); + } else { + + /** + * Filter the value of a user field in a standard context. + * + * The dynamic portion of the hook name, $field, refers to the prefixed user + * field being filtered, such as 'user_login', 'user_email', 'first_name', etc. + * + * @since 2.9.0 + * + * @param mixed $value The user object value to sanitize. + * @param int $user_id User ID. + * @param string $context The context to filter within. + */ + $value = apply_filters( "user_{$field}", $value, $user_id, $context ); + } } if ( 'user_url' == $field ) @@ -1228,7 +1454,6 @@ function username_exists( $username ) { * Checks whether the given email exists. * * @since 2.1.0 - * @uses $wpdb * * @param string $email Email. * @return bool|int The user's ID on success, and false on failure. @@ -1252,6 +1477,14 @@ function email_exists( $email ) { function validate_username( $username ) { $sanitized = sanitize_user( $username, true ); $valid = ( $sanitized == $username ); + /** + * Filter whether the provided username is valid or not. + * + * @since 2.0.1 + * + * @param bool $valid Whether given username is valid. + * @param string $username Username to check. + */ return apply_filters( 'validate_username', $valid, $username ); } @@ -1287,10 +1520,10 @@ function validate_username( $username ) { * 'yim' - User's Yahoo IM account. * * @since 2.0.0 - * @uses $wpdb WordPress database layer. - * @uses apply_filters() Calls filters for most of the $userdata fields with the prefix 'pre_user'. See note above. - * @uses do_action() Calls 'profile_update' hook when updating giving the user's ID - * @uses do_action() Calls 'user_register' hook when creating a new user giving the user's ID + * + * @global wpdb $wpdb WordPress database object for queries. + * + * @todo Hash-notate arguments array. * * @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. @@ -1317,7 +1550,17 @@ function wp_insert_user( $userdata ) { } $user_login = sanitize_user($user_login, true); - $user_login = apply_filters('pre_user_login', $user_login); + + /** + * Filter a username after it has been sanitized. + * + * This filter is called before the user is created or updated. + * + * @since 2.0.3 + * + * @param string $user_login Username after it has been sanitized. + */ + $user_login = apply_filters( 'pre_user_login', $user_login ); //Remove any non-printable chars from the login string to see if we have ended up with an empty username $user_login = trim($user_login); @@ -1330,30 +1573,78 @@ function wp_insert_user( $userdata ) { if ( empty($user_nicename) ) $user_nicename = sanitize_title( $user_login ); - $user_nicename = apply_filters('pre_user_nicename', $user_nicename); + + /** + * Filter a user's nicename before the user is created or updated. + * + * @since 2.0.3 + * + * @param string $user_nicename The user's nicename. + */ + $user_nicename = apply_filters( 'pre_user_nicename', $user_nicename ); if ( empty($user_url) ) $user_url = ''; - $user_url = apply_filters('pre_user_url', $user_url); + + /** + * Filter a user's URL before the user is created or updated. + * + * @since 2.0.3 + * + * @param string $user_url The user's URL. + */ + $user_url = apply_filters( 'pre_user_url', $user_url ); if ( empty($user_email) ) $user_email = ''; - $user_email = apply_filters('pre_user_email', $user_email); + + /** + * Filter a user's email before the user is created or updated. + * + * @since 2.0.3 + * + * @param string $user_email The user's email. + */ + $user_email = apply_filters( 'pre_user_email', $user_email ); if ( !$update && ! defined( 'WP_IMPORTING' ) && email_exists($user_email) ) return new WP_Error( 'existing_user_email', __( 'Sorry, that email address is already used!' ) ); if ( empty($nickname) ) $nickname = $user_login; - $nickname = apply_filters('pre_user_nickname', $nickname); + + /** + * Filter a user's nickname before the user is created or updated. + * + * @since 2.0.3 + * + * @param string $nickname The user's nickname. + */ + $nickname = apply_filters( 'pre_user_nickname', $nickname ); if ( empty($first_name) ) $first_name = ''; - $first_name = apply_filters('pre_user_first_name', $first_name); + + /** + * Filter a user's first name before the user is created or updated. + * + * @since 2.0.3 + * + * @param string $first_name The user's first name. + */ + $first_name = apply_filters( 'pre_user_first_name', $first_name ); if ( empty($last_name) ) $last_name = ''; - $last_name = apply_filters('pre_user_last_name', $last_name); + + /** + * Filter a user's last name before the user is created or updated. + * + * @since 2.0.3 + * + * @param string $last_name The user's last name. + */ + $last_name = apply_filters( 'pre_user_last_name', $last_name ); if ( empty( $display_name ) ) { if ( $update ) @@ -1368,11 +1659,27 @@ function wp_insert_user( $userdata ) { else $display_name = $user_login; } + + /** + * Filter a user's display name before the user is created or updated. + * + * @since 2.0.3 + * + * @param string $display_name The user's display name. + */ $display_name = apply_filters( 'pre_user_display_name', $display_name ); if ( empty($description) ) $description = ''; - $description = apply_filters('pre_user_description', $description); + + /** + * Filter a user's description before the user is created or updated. + * + * @since 2.0.3 + * + * @param string $description The user's description. + */ + $description = apply_filters( 'pre_user_description', $description ); if ( empty($rich_editing) ) $rich_editing = 'true'; @@ -1431,10 +1738,26 @@ function wp_insert_user( $userdata ) { wp_cache_delete($user_id, 'users'); wp_cache_delete($user_login, 'userlogins'); - if ( $update ) - do_action('profile_update', $user_id, $old_user_data); - else - do_action('user_register', $user_id); + if ( $update ) { + /** + * Fires immediately after an existing user is updated. + * + * @since 2.0.0 + * + * @param int $user_id User ID. + * @param object $old_user_data Object containing user's data prior to update. + */ + do_action( 'profile_update', $user_id, $old_user_data ); + } else { + /** + * Fires immediately after a new user is registered. + * + * @since 1.5.0 + * + * @param int $user_id User ID. + */ + do_action( 'user_register', $user_id ); + } return $user_id; } @@ -1449,7 +1772,8 @@ function wp_insert_user( $userdata ) { * cleared. * * @since 2.0.0 - * @see wp_insert_user() For what fields can be set in $userdata + * + * @see wp_insert_user() For what fields can be set in $userdata. * * @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. @@ -1587,7 +1911,7 @@ function _wp_get_user_contactmethods( $user = null ) { * 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. * - * @uses $wpdb WordPress Database object + * @global wpdb $wpdb WordPress database object for queries. * * @param string $key Hash to validate sending user's password. * @param string $login The user login. @@ -1643,6 +1967,14 @@ function check_password_reset_key($key, $login) { * @param string $new_pass New password for the user in plaintext */ function reset_password( $user, $new_pass ) { + /** + * Fires before the user's password is reset. + * + * @since 1.5.0 + * + * @param object $user The user. + * @param string $new_pass New user password. + */ do_action( 'password_reset', $user, $new_pass ); wp_set_password( $new_pass, $user->ID ); @@ -1662,6 +1994,13 @@ function register_new_user( $user_login, $user_email ) { $errors = new WP_Error(); $sanitized_user_login = sanitize_user( $user_login ); + /** + * Filter the email address of a user being registered. + * + * @since 2.1.0 + * + * @param string $user_email The email address of the new user. + */ $user_email = apply_filters( 'user_registration_email', $user_email ); // Check the username @@ -1684,8 +2023,35 @@ function register_new_user( $user_login, $user_email ) { $errors->add( 'email_exists', __( 'ERROR: This email is already registered, please choose another one.' ) ); } + /** + * Fires when submitting registration form data, before the user is created. + * + * @since 2.1.0 + * + * @param string $sanitized_user_login The submitted username after being sanitized. + * @param string $user_email The submitted email. + * @param WP_Error $errors Contains any errors with submitted username and email, + * e.g., an empty field, an invalid username or email, + * or an existing username or email. + */ do_action( 'register_post', $sanitized_user_login, $user_email, $errors ); + /** + * Filter the errors encountered when a new user is being registered. + * + * The filtered WP_Error object may, for example, contain errors for an invalid + * or existing username or email address. A WP_Error object should always returned, + * but may or may not contain errors. + * + * If any errors are present in $errors, this will abort the user's registration. + * + * @since 2.1.0 + * + * @param WP_Error $errors A WP_Error object containing any errors encountered + * during registration. + * @param string $sanitized_user_login User's username after it has been sanitized. + * @param string $user_email User's email. + */ $errors = apply_filters( 'registration_errors', $errors, $sanitized_user_login, $user_email ); if ( $errors->get_error_code() )