diff --git wp-includes/user.php wp-includes/user.php index 9a60cd2..a96b612 100644 --- wp-includes/user.php +++ wp-includes/user.php @@ -38,11 +38,36 @@ function wp_signon( $credentials = '', $secure_cookie = '' ) { $credentials['remember'] = false; // TODO do we deprecate the wp_authentication action? + /** + * 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. + * @param string $user_password. + */ do_action_ref_array('wp_authenticate', array(&$credentials['user_login'], &$credentials['user_password'])); if ( '' === $secure_cookie ) $secure_cookie = is_ssl(); + /** + * Filters whether the sign-on cookie should only be transmitted over a secure HTTPS + * connection from the client. + * + * @since 3.1.0 + * + * @param bool $secure_cookie When set to true, the cookie will only be set if a secure connection exists. + * @param array $args { + * User credentials. + * + * @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. + * } + */ $secure_cookie = apply_filters('secure_signon_cookie', $secure_cookie, $credentials); global $auth_secure_cookie; // XXX ugly hack to pass this to wp_authenticate_cookie @@ -61,7 +86,17 @@ function wp_signon( $credentials = '', $secure_cookie = '' ) { } wp_set_auth_cookie($user->ID, $credentials['remember'], $secure_cookie); - do_action('wp_login', $user->user_login, $user); + + $user_login = $user->user_login; + /** + * Triggered after the user has successfully logged in. + * + * @since 1.5.2 + * + * @param string $user_login The user's username. + * @param WP_User $user The logged-in user. + */ + do_action('wp_login', $user_login, $user); return $user; } @@ -92,6 +127,18 @@ 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() ) ); + /** + * Filters whether the given user can be authenticated with the provided $password. + * + * This allows plug-ins to add additional authentication conditions. Please note that the filtered + * value is originally a WP_User,but hooked callbacks may recieve a WP_Error if authentication has + * failed in an earlier callback. + * + * @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,7 +185,16 @@ function wp_authenticate_cookie($user, $username, $password) { */ function wp_authenticate_spam_check( $user ) { if ( $user && is_a( $user, 'WP_User' ) && is_multisite() ) { - $spammed = apply_filters( 'check_is_user_spammed', is_user_spammy(), $user ); + $spammed = is_user_spammy(); + /** + * Filters whether the user has been marked as a spammer. + * + * @since 3.7.0 + * + * @param bool $spammed True if the user is considered a spammer. + * @param WP_User $user The user to check against. + */ + $spammed = apply_filters( 'check_is_user_spammed', $spammed, $user ); if ( $spammed ) return new WP_Error( 'spammer_account', __( 'ERROR: Your account has been marked as a spammer.' ) ); @@ -162,6 +218,14 @@ function count_user_posts($userid) { $count = $wpdb->get_var( "SELECT COUNT(*) FROM $wpdb->posts $where" ); + /** + * Filters the number of posts a user has written. + * + * @since 2.7.0 + * + * @param int $count The number of posts the user has posted. + * @param int $userid The ID of the user. + */ return apply_filters('get_usernumposts', $count, $userid); } @@ -256,6 +320,17 @@ function get_user_option( $option, $user = 0, $deprecated = '' ) { else $result = false; + /** + * Filter a specific option value for a user. + * + * `$option` in this filter refers to the user option name. + * + * @since 2.5.0 + * + * @param mixed $result The value for the user's option. + * @param string $option The name of the option being retrieved. + * @param WP_User $user User object of the user whose option is being retrieved. + */ return apply_filters("get_user_option_{$option}", $result, $option, $user); } @@ -494,6 +569,18 @@ class WP_User_Query { $search_columns = array('user_login', 'user_nicename'); } + /** + * Filters the columns which are searched in a WP_User_Query search. + * + * The default colummns 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 term being searched. + * @param WP_User_Query $this The current WP_User_Query. + */ $search_columns = apply_filters( 'user_search_columns', $search_columns, $search, $this ); $this->query_where .= $this->get_search_sql( $search, $search_columns, $wild ); @@ -546,6 +633,15 @@ class WP_User_Query { $this->query_where .= " AND $wpdb->users.ID NOT IN ($ids)"; } + /** + * Triggered 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 user query, passed by reference. + */ do_action_ref_array( 'pre_user_query', array( &$this ) ); } @@ -566,8 +662,16 @@ class WP_User_Query { $this->results = $wpdb->get_col("SELECT $this->query_fields $this->query_from $this->query_where $this->query_orderby $this->query_limit"); } + /** + * Filters the SQL command for number of users matching the WP_User_Query + * + * @since 3.2.0 + * + * @param string $sql The SQL command to count the number of matching users. + */ if ( isset( $qv['count_total'] ) && $qv['count_total'] ) - $this->total_users = $wpdb->get_var( apply_filters( 'found_users_query', 'SELECT FOUND_ROWS()' ) ); + $sql = 'SELECT FOUND_ROWS()'; + $this->total_users = $wpdb->get_var( apply_filters( 'found_users_query', $sql ) ); if ( !$this->results ) return; @@ -774,6 +878,16 @@ function get_blogs_of_user( $user_id, $all = false ) { } } + /** + * Filters the blogs belonging to the specified user. + * + * @since 3.1.0 + * + * @param array $blogs An array of blog objects belonging to the user. + * @param int $user_id The ID of the user. + * @param bool $all True if $blogs should conain all blogs, false if it should only + * contain blogs that are not marked as deleted, archived, or spam. + */ return apply_filters( 'get_blogs_of_user', $blogs, $user_id, $all ); } @@ -1092,7 +1206,14 @@ function wp_dropdown_users( $args = '' ) { $output .= ""; } - + + /** + * Filters the HTML of a dropdown of users. + * + * @since 2.3.0 + * + * @param string $output HTML generated by `wp_dropdown_users()`. + */ $output = apply_filters('wp_dropdown_users', $output); if ( $echo ) @@ -1138,8 +1259,21 @@ function sanitize_user_field($field, $value, $user_id, $context) { if ( 'edit' == $context ) { if ( $prefixed ) { + //duplicate hook $value = apply_filters("edit_{$field}", $value, $user_id); } else { + /** + * Filter and sanitize the value of the prefixed field (for editing). + * + * 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 The user ID. + */ $value = apply_filters("edit_user_{$field}", $value, $user_id); } @@ -1149,16 +1283,43 @@ function sanitize_user_field($field, $value, $user_id, $context) { $value = esc_attr($value); } else if ( 'db' == $context ) { if ( $prefixed ) { + //Dupicate hook $value = apply_filters("pre_{$field}", $value); } else { + /** + * Filter and sanitize the value of the prefixed field (for database use). + * + * 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 ) + if ( $prefixed ){ + //Duplicate hook $value = apply_filters($field, $value, $user_id, $context); - else + }else{ + /** + * Filter and sanitize the value of the prefixed field (for other contexts). + * + * 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 The User ID. + * @param string $context The context to filter for. + */ $value = apply_filters("user_{$field}", $value, $user_id, $context); + } } if ( 'user_url' == $field ) @@ -1250,6 +1411,14 @@ function email_exists( $email ) { function validate_username( $username ) { $sanitized = sanitize_user( $username, true ); $valid = ( $sanitized == $username ); + /** + * Filters 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 ); } @@ -1321,6 +1490,15 @@ function wp_insert_user( $userdata ) { } $user_login = sanitize_user($user_login, true); + /** + * Filters the 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 @@ -1334,14 +1512,40 @@ function wp_insert_user( $userdata ) { if ( empty($user_nicename) ) $user_nicename = sanitize_title( $user_login ); + + /** + * Filters the 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 = ''; + + /** + * Filters the 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 = ''; + + /** + * Filters the 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) ) @@ -1349,14 +1553,38 @@ function wp_insert_user( $userdata ) { if ( empty($nickname) ) $nickname = $user_login; + + /** + * Filters the 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 = ''; + + /** + * Filters the 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 = ''; + + /** + * Filters the 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 ) ) { @@ -1372,10 +1600,26 @@ function wp_insert_user( $userdata ) { else $display_name = $user_login; } + + /** + * Filters the 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 = ''; + + /** + * Filters the 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) ) @@ -1435,10 +1679,26 @@ function wp_insert_user( $userdata ) { wp_cache_delete($user_id, 'users'); wp_cache_delete($user_login, 'userlogins'); - if ( $update ) + if ( $update ){ + /** + * Triggered after the user is updated. + * + * @since 2.0.0 + * + * @param int $user_id The user ID. + * @param object $old_user_data User's data prior to update as a raw object. + */ do_action('profile_update', $user_id, $old_user_data); - else + }else{ + /** + * Triggered after the user is created. + * + * @since 1.5.2 + * + * @param int $user_id The user ID + */ do_action('user_register', $user_id); + } return $user_id; } @@ -1648,8 +1908,17 @@ function check_password_reset_key($key, $login) { * @param string $new_pass New password for the user in plaintext */ function reset_password( $user, $new_pass ) { + + /** + * Triggered before the user's password is reset to $new_pass. + * + * @since Unknown + * + * @param int $user_id The user ID. + * @param object $old_user_data User's data prior to update as a raw object. + */ do_action( 'password_reset', $user, $new_pass ); - + //@since is uknown but exists before 1.5 wp_set_password( $new_pass, $user->ID ); update_user_option( $user->ID, 'default_password_nag', false, true ); @@ -1667,6 +1936,15 @@ function register_new_user( $user_login, $user_email ) { $errors = new WP_Error(); $sanitized_user_login = sanitize_user( $user_login ); + /** + * Filters 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 @@ -1689,8 +1967,33 @@ function register_new_user( $user_login, $user_email ) { $errors->add( 'email_exists', __( 'ERROR: This email is already registered, please choose another one.' ) ); } + /** + * Triggered 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 sanitization. + * @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 ); + /** + * Filters 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 which contains any errors encountered during registration. + * @param string $sanitized_user_login The user's username after it has been sanitized. + * @param string $user_email The user's email. + */ $errors = apply_filters( 'registration_errors', $errors, $sanitized_user_login, $user_email ); if ( $errors->get_error_code() )