Index: src/wp-includes/user.php =================================================================== --- src/wp-includes/user.php (revision 26844) +++ src/wp-includes/user.php (working copy) @@ -38,12 +38,37 @@ $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.2 + * + * @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 $args { + * 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,7 +86,16 @@ } wp_set_auth_cookie($user->ID, $credentials['remember'], $secure_cookie); - do_action('wp_login', $user->user_login, $user); + + /** + * Triggered after the user has successfully logged in. + * + * @since 1.5.2 + * + * @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; } @@ -92,6 +126,15 @@ if ( !$user ) return new WP_Error( 'invalid_username', sprintf( __( 'ERROR: Invalid username. Lost your password?' ), wp_lostpassword_url() ) ); + /** + * Filter whether the given user can be authenticated with the provided $password. + * + * @since 2.5.0 + * + * @param WP_User|WP_Error $user WP_User object or WP_Error object if a previous + * callback failed authentication. + * @param string $password The password to check against the user. + */ $user = apply_filters('wp_authenticate_user', $user, $password); if ( is_wp_error($user) ) return $user; @@ -138,6 +181,14 @@ */ 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 spam. + * @param WP_User $user The user to check against. + */ $spammed = apply_filters( 'check_is_user_spammed', is_user_spammy(), $user ); if ( $spammed ) @@ -162,7 +213,15 @@ $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 ); } /** @@ -258,7 +317,19 @@ 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 ); } /** @@ -496,6 +567,18 @@ $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 The 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 ); @@ -548,6 +631,18 @@ $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 1.5.2 + * + * @param WP_User_Query $this The current WP_User_Query instance, + * passed by reference. + */ do_action_ref_array( 'pre_user_query', array( &$this ) ); } @@ -568,6 +663,15 @@ $this->results = $wpdb->get_col("SELECT $this->query_fields $this->query_from $this->query_where $this->query_orderby $this->query_limit"); } + /** + * Filter SELECT_FOUND_ROWS value for the current WP_User_Query instance. + * + * @since 3.2.0 + * + * @global wpdb $wpdb WordPress database object. + * + * @param string $sql The SELECT_FOUND_ROWS() value 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()' ) ); @@ -776,6 +880,16 @@ } } + /** + * Filter list of blogs a user belongs to. + * + * @since 3.1.0 + * + * @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 blog, including + * those marked 'deleted', 'archived', or 'spam'. Default false. + */ return apply_filters( 'get_blogs_of_user', $blogs, $user_id, $all ); } @@ -1094,9 +1208,16 @@ $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 ); - $output = apply_filters('wp_dropdown_users', $output); - if ( $echo ) echo $output; @@ -1140,8 +1261,21 @@ 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 { + /** + * 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); } @@ -1151,16 +1285,43 @@ $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 + 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 ) @@ -1252,6 +1413,14 @@ function validate_username( $username ) { $sanitized = sanitize_user( $username, true ); $valid = ( $sanitized == $username ); + /** + * Filter whether the provided username is valid or not. + * + * @since 2.0.11 + * + * @param bool $valid Whether username given is valid. + * @param string $username The username to check. + */ return apply_filters( 'validate_username', $valid, $username ); } @@ -1317,7 +1486,17 @@ } $user_login = sanitize_user($user_login, true); - $user_login = apply_filters('pre_user_login', $user_login); + /** + * Filter a username after it has been sanitized, but before + * the user is created or updated. + * + * This hook is called before the user is created or updated. + * + * @since 2.0.11 + * + * @param string $user_login The 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 +1509,80 @@ 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. + * + * This hook is called before the user is created or updated. + * + * @since 2.0.11 + * + * @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.11 + * + * @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.11 + * + * @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.11 + * + * @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.11 + * + * @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.11 + * + * @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 +1597,27 @@ else $display_name = $user_login; } + + /** + * Filter a user's display name before the user is created or updated. + * + * @since 2.0.11 + * + * @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.11 + * + * @param string $description The user's description. + */ + $description = apply_filters( 'pre_user_description', $description ); if ( empty($rich_editing) ) $rich_editing = 'true'; @@ -1431,10 +1676,26 @@ wp_cache_delete($user_id, 'users'); wp_cache_delete($user_login, 'userlogins'); - if ( $update ) + 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 - do_action('user_register', $user_id); + } else { + /** + * Fires immediately after a new user is registered. + * + * @since 1.5.2 + * + * @param int $user_id User ID. + */ + do_action( 'user_register', $user_id ); + } return $user_id; } @@ -1643,6 +1904,15 @@ * @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 Unknown + * + * @param int $user_id User ID. + * @param object $old_user_data User's data prior to update as a raw object. + */ do_action( 'password_reset', $user, $new_pass ); wp_set_password( $new_pass, $user->ID ); @@ -1662,6 +1932,15 @@ $errors = new WP_Error(); $sanitized_user_login = sanitize_user( $user_login ); + /** + * Filter the email address of a user being registered. + * + * This hooks is triggered before the user is created. + * + * @since 2.1.0 + * + * @param string $user_email The email of the new user. + */ $user_email = apply_filters( 'user_registration_email', $user_email ); // Check the username @@ -1684,8 +1963,34 @@ $errors->add( 'email_exists', __( 'ERROR: This email is already registered, please choose another one.' ) ); } + /** + * FIRES when registration form data is submitted, and before the user has been 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 the submitted username and + * email (e.g. invalid, already exists). + */ do_action( 'register_post', $sanitized_user_login, $user_email, $errors ); + /** + * Filter the errors encountered when a new user is beng registerered. + * + * The filtered WP_Error object may, for example, contain errors for an invalid + * or existing username or email. 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() )