From e73caae160ff9a2c92295aa338f695c67445c0c3 Mon Sep 17 00:00:00 2001 From: Drew Jaynes Date: Sat, 4 Jan 2014 06:18:10 +0000 Subject: [PATCH] Inline documentation for hooks in wp-includes/user.php. Props stephenharris, kpdesign. Fixes #25533. Built from https://develop.svn.wordpress.org/trunk@26901 git-svn-id: http://core.svn.wordpress.org/trunk@26784 1a063a9b-81f0-0310-95a4-ce76da25c4cd --- wp-includes/user.php | 342 +++++++++++++++++++++++++++++++++++++++---- 1 file changed, 315 insertions(+), 27 deletions(-) diff --git a/wp-includes/user.php b/wp-includes/user.php index 3bc29e14af..7dd26e4156 100644 --- a/wp-includes/user.php +++ b/wp-includes/user.php @@ -38,12 +38,38 @@ function wp_signon( $credentials = '', $secure_cookie = '' ) { $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 + * + * @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,7 +87,15 @@ 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; } @@ -92,7 +126,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; @@ -138,6 +181,14 @@ function wp_authenticate_cookie($user, $username, $password) { */ 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 ) @@ -162,7 +213,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 ); } /** @@ -258,7 +317,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 ); } /** @@ -496,6 +566,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 ); @@ -548,6 +630,18 @@ 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 ) ); } @@ -568,6 +662,15 @@ 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"); } + /** + * 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 +879,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 ); } @@ -1095,7 +1208,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; @@ -1140,9 +1260,21 @@ 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 +1283,41 @@ 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 ) @@ -1252,6 +1409,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 ); } @@ -1317,7 +1482,16 @@ 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 +1504,72 @@ 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 +1584,25 @@ 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 +1661,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; } @@ -1643,6 +1889,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 +1916,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 +1945,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() )