Ticket #25533: 25533.diff

wp-includes/user.php

@@ -38 +38 @@
                 $credentials['remember'] = false;
 
         // TODO do we deprecate the wp_authentication action?
+        /**
+         * Triggered before the user is logged in.
+         * 
+         * 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 +85 @@
         }
 
         wp_set_auth_cookie($user->ID, $credentials['remember'], $secure_cookie);
+        
+        /**
+         * Triggered after the user has successfully logged in.
+         *
+         * @since 1.5.2
+         *
+         * @param string $user_login The user's usersname
+         * @param WP_User $user The logged-in user 
+         */
         do_action('wp_login', $user->user_login, $user);
         return $user;
 }
@@ -92 +125 @@
         if ( !$user )
                 return new WP_Error( 'invalid_username', sprintf( __( '<strong>ERROR</strong>: Invalid username. <a href="%s" title="Password Lost and Found">Lost your password</a>?' ), wp_lostpassword_url() ) );
 
+        /**
+         * Returns either a WP_User or WP_Error object depending on 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 The user to authenticate as a WP_User object or a WP_Error object if a previous callback as 'failed' the 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 +182 @@
  */
 function wp_authenticate_spam_check( $user ) {
         if ( $user && is_a( $user, 'WP_User' ) && is_multisite() ) {
+                /**
+                 * 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', is_user_spammy(), $user );
 
                 if ( $spammed )
@@ -162 +214 @@
 
         $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 +316 @@
         else
                 $result = false;
 
+        /**
+         * Filter a specific option value for a user.
+         *
+         * @since 2.5.0
+         *
+         * @param mixed 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 +563 @@
                                         $search_columns = array('user_login', 'user_nicename');
                         }
 
+                        /**
+                         * Filters the columns which are searched in a WP_User_Query search.
+                         *
+                         * @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 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 +624 @@
                         $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 WP_User_Query is passed by reference and can be modified. It contains SQL
+                 * parts formed from parsing WP_User_Query. 
+                 *
+                 * @since 1.5.2
+                 *
+                 * @param WP_User_Query $this The user query.
+                 */
                 do_action_ref_array( 'pre_user_query', array( &$this ) );
         }
 
@@ -566 +654 @@
                         $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
+                 */
                 if ( isset( $qv['count_total'] ) && $qv['count_total'] )
                         $this->total_users = $wpdb->get_var( apply_filters( 'found_users_query', 'SELECT FOUND_ROWS()' ) );
 
@@ -774 +869 @@
                 }
         }
 
+        /**
+         * Filters the blogs belonging to the specified user.
+         *
+         * @since 3.1.0
+         *
+         * @param array 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 +1196 @@
 
                 $output .= "</select>";
         }
-
+        
+        /**
+         * Filters the HTML of a dropdown of users.
+         *
+         * @since 2.3.0
+         *
+         * @param string HTML generated by `wp_dropdown_users()`.
+         */
         $output = apply_filters('wp_dropdown_users', $output);
 
         if ( $echo )
@@ -1138 +1249 @@
 
         if ( 'edit' == $context ) {
                 if ( $prefixed ) {
+                        /**
+                         * Filter and sanitize the value of the prefixed field (for editing). 
+                         *
+                         * @since 2.3.0
+                         *
+                         * @param mixed $value The user object value to sanitize.
+                         * @param int $user_id The user ID.
+                         */
                         $value = apply_filters("edit_{$field}", $value, $user_id);
                 } else {
+                        /**
+                         * Non prefixed version...
+                         * @since 2.9.0
+                         * @see edit_user_{$field} filter above
+                         */
                         $value = apply_filters("edit_user_{$field}", $value, $user_id);
                 }
 
@@ -1149 +1273 @@
                         $value = esc_attr($value);
         } else if ( 'db' == $context ) {
                 if ( $prefixed ) {
+                        /**
+                         * Filter and sanitize the value of the prefixed field (for database use).
+                         *
+                         * @since 2.3.0
+                         *
+                         * @param mixed $value The user object value to sanitize.
+                         */
                         $value = apply_filters("pre_{$field}", $value);
                 } else {
+                        /**
+                         * Non prefixed version...
+                         * @see pre_user_{$field} filter above
+                         * @since 2.9.0
+                         */
                         $value = apply_filters("pre_user_{$field}", $value);
                 }
         } else {
                 // Use display filters by default.
-                if ( $prefixed )
+                if ( $prefixed ){
+                        /**
+                         * Filter and sanitize the value of the prefixed field (for other contexts).
+                         *
+                         * @since 2.3.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($field, $value, $user_id, $context);
-                else
+                }else{
+                        /**
+                         * Non prefixed version...
+                         * @see user_{$field} filter above
+                         * @since 2.9.0
+                         */
                         $value = apply_filters("user_{$field}", $value, $user_id, $context);
+                }
         }
 
         if ( 'user_url' == $field )
@@ -1250 +1401 @@
 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 Whether username given is valid.
+         * @param string The username to check.
+         */
         return apply_filters( 'validate_username', $valid, $username );
 }
 
@@ -1321 +1480 @@
         }
 
         $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 +1502 @@
 
         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
+         */
         $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
+         */
         $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
+         */
         $user_email = apply_filters('pre_user_email', $user_email);
 
         if ( !$update && ! defined( 'WP_IMPORTING' ) && email_exists($user_email) )
@@ -1349 +1543 @@
 
         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
+         */
         $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
+         */
         $last_name = apply_filters('pre_user_last_name', $last_name);
 
         if ( empty( $display_name ) ) {
@@ -1372 +1590 @@
                 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
+         */
         $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
+         */
         $description = apply_filters('pre_user_description', $description);
 
         if ( empty($rich_editing) )
@@ -1435 +1669 @@
         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 +1898 @@
  * @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 +1926 @@
         $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 +1957 @@
                 $errors->add( 'email_exists', __( '<strong>ERROR</strong>: 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() )