WordPress.org
Get WordPress

Make WordPress Core

Ticket #25533: 25533.2.diff

File 25533.2.diff, 16.6 KB (added by stephenharris, 13 years ago)

  • wp-includes/user.php 

    diff --git wp-includes/user.php wp-includes/user.php
index 9a60cd2..a96b612 100644
    function wp_signon( $credentials = '', $secure_cookie = '' ) {  
    3838                $credentials['remember'] = false;
    3939
    4040        // TODO do we deprecate the wp_authentication action?
     41        /**
     42         * Fires before the user is authenticated.
     43         *
     44         * The variables passed to the callbacks are passed by reference and can be modified by callback functions.
     45         * 
     46         * @since 1.5.2
     47         *
     48         * @param string $user_login.
     49         * @param string $user_password.
     50         */
    4151        do_action_ref_array('wp_authenticate', array(&$credentials['user_login'], &$credentials['user_password']));
    4252
    4353        if ( '' === $secure_cookie )
    4454                $secure_cookie = is_ssl();
    4555
     56        /**
     57         * Filters whether the sign-on cookie should only be transmitted over a secure HTTPS
     58         * connection from the client.
     59         *
     60         * @since 3.1.0
     61         *
     62         * @param bool  $secure_cookie When set to true, the cookie will only be set if a secure connection exists.
     63         * @param array $args {
     64         *     User credentials.
     65         *
     66         *     @type string $user_login    Username.
     67         *     @type string $user_password Password entered.
     68         *     @type bool   $remember      Whether to 'remember' the user. Increases the time that the cookie will be kept.
     69         * }
     70         */
    4671        $secure_cookie = apply_filters('secure_signon_cookie', $secure_cookie, $credentials);
    4772
    4873        global $auth_secure_cookie; // XXX ugly hack to pass this to wp_authenticate_cookie
    … … function wp_signon( $credentials = '', $secure_cookie = '' ) {  
    6186        }
    6287
    6388        wp_set_auth_cookie($user->ID, $credentials['remember'], $secure_cookie);
    64         do_action('wp_login', $user->user_login, $user);
     89       
     90        $user_login = $user->user_login;
     91        /**
     92         * Triggered after the user has successfully logged in.
     93         *
     94         * @since 1.5.2
     95         *
     96         * @param string  $user_login The user's username.
     97         * @param WP_User $user       The logged-in user.
     98         */
     99        do_action('wp_login', $user_login, $user);
    65100        return $user;
    66101}
    67102
    … … function wp_authenticate_username_password($user, $username, $password) {  
    92127        if ( !$user )
    93128                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() ) );
    94129
     130        /**
     131         * Filters whether the given user can be authenticated with the provided $password.
     132         *
     133         * This allows plug-ins to add additional authentication conditions. Please note that the filtered
     134         * value is originally a WP_User,but hooked callbacks may recieve a WP_Error if authentication has
     135         * failed in an earlier callback.
     136         *
     137         * @since 2.5.0
     138         *
     139         * @param WP_User|WP_Error $user WP_User object or WP_Error object if a previous callback failed authentication.
     140         * @param string $password The password to check against the user.
     141         */
    95142        $user = apply_filters('wp_authenticate_user', $user, $password);
    96143        if ( is_wp_error($user) )
    97144                return $user;
    … … function wp_authenticate_cookie($user, $username, $password) {  
    138185 */
    139186function wp_authenticate_spam_check( $user ) {
    140187        if ( $user && is_a( $user, 'WP_User' ) && is_multisite() ) {
    141                 $spammed = apply_filters( 'check_is_user_spammed', is_user_spammy(), $user );
     188                $spammed = is_user_spammy();
     189                /**
     190                 * Filters whether the user has been marked as a spammer.
     191                 *
     192                 * @since 3.7.0
     193                 *
     194                 * @param bool $spammed True if the user is considered a spammer.
     195                 * @param WP_User $user The user to check against.
     196                 */
     197                $spammed = apply_filters( 'check_is_user_spammed', $spammed, $user );
    142198
    143199                if ( $spammed )
    144200                        return new WP_Error( 'spammer_account', __( '<strong>ERROR</strong>: Your account has been marked as a spammer.' ) );
    … … function count_user_posts($userid) {  
    162218
    163219        $count = $wpdb->get_var( "SELECT COUNT(*) FROM $wpdb->posts $where" );
    164220
     221        /**
     222         * Filters the number of posts a user has written.
     223         *
     224         * @since 2.7.0
     225         *
     226         * @param int $count The number of posts the user has posted.
     227         * @param int $userid The ID of the user.
     228         */
    165229        return apply_filters('get_usernumposts', $count, $userid);
    166230}
    167231
    … … function get_user_option( $option, $user = 0, $deprecated = '' ) {  
    256320        else
    257321                $result = false;
    258322
     323        /**
     324         * Filter a specific option value for a user.
     325         *
     326         * `$option` in this filter refers to the user option name.
     327         *
     328         * @since 2.5.0
     329         *
     330         * @param mixed   $result The value for the user's option.
     331         * @param string  $option The name of the option being retrieved.
     332         * @param WP_User $user   User object of the user whose option is being retrieved.
     333         */
    259334        return apply_filters("get_user_option_{$option}", $result, $option, $user);
    260335}
    261336
    … … class WP_User_Query {  
    494569                                        $search_columns = array('user_login', 'user_nicename');
    495570                        }
    496571
     572                        /**
     573                         * Filters the columns which are searched in a WP_User_Query search.
     574                         *
     575                         * The default colummns depend on the search term and include `user_email`,
     576                         * `user_login`, `ID`, `user_url` and `user_nicename`.
     577                         *
     578                         * @since 3.6.0
     579                         *
     580                         * @param array         $search_columns Array of column names to be searched.
     581                         * @param string        $search         The term being searched.
     582                         * @param WP_User_Query $this           The current WP_User_Query.
     583                         */
    497584                        $search_columns = apply_filters( 'user_search_columns', $search_columns, $search, $this );
    498585
    499586                        $this->query_where .= $this->get_search_sql( $search, $search_columns, $wild );
    … … class WP_User_Query {  
    546633                        $this->query_where .= " AND $wpdb->users.ID NOT IN ($ids)";
    547634                }
    548635
     636                /**
     637                 * Triggered after the WP_User_Query has been parsed and before the query is executed.
     638                 *
     639                 * The passed WP_User_Query object contains SQL parts formed from parsing the given query.
     640                 *
     641                 * @since 1.5.2
     642                 *
     643                 * @param WP_User_Query $this The user query, passed by reference.
     644                 */
    549645                do_action_ref_array( 'pre_user_query', array( &$this ) );
    550646        }
    551647
    … … class WP_User_Query {  
    566662                        $this->results = $wpdb->get_col("SELECT $this->query_fields $this->query_from $this->query_where $this->query_orderby $this->query_limit");
    567663                }
    568664
     665                /**
     666                 * Filters the SQL command for number of users matching the WP_User_Query
     667                 *
     668                 * @since 3.2.0
     669                 *
     670                 * @param string $sql The SQL command to count the number of matching users.
     671                 */
    569672                if ( isset( $qv['count_total'] ) && $qv['count_total'] )
    570                         $this->total_users = $wpdb->get_var( apply_filters( 'found_users_query', 'SELECT FOUND_ROWS()' ) );
     673                        $sql = 'SELECT FOUND_ROWS()';
     674                        $this->total_users = $wpdb->get_var( apply_filters( 'found_users_query', $sql ) );
    571675
    572676                if ( !$this->results )
    573677                        return;
    … … function get_blogs_of_user( $user_id, $all = false ) {  
    774878                }
    775879        }
    776880
     881        /**
     882         * Filters the blogs belonging to the specified user.
     883         *
     884         * @since 3.1.0
     885         *
     886         * @param array $blogs   An array of blog objects belonging to the user.
     887         * @param int   $user_id The ID of the user.
     888         * @param bool  $all     True if $blogs should conain all blogs, false if it should only
     889         *                       contain blogs that are not marked as deleted, archived, or spam.
     890         */
    777891        return apply_filters( 'get_blogs_of_user', $blogs, $user_id, $all );
    778892}
    779893
    … … function wp_dropdown_users( $args = '' ) {  
    10921206
    10931207                $output .= "</select>";
    10941208        }
    1095 
     1209       
     1210        /**
     1211         * Filters the HTML of a dropdown of users.
     1212         *
     1213         * @since 2.3.0
     1214         *
     1215         * @param string $output HTML generated by `wp_dropdown_users()`.
     1216         */
    10961217        $output = apply_filters('wp_dropdown_users', $output);
    10971218
    10981219        if ( $echo )
    … … function sanitize_user_field($field, $value, $user_id, $context) {  
    11381259
    11391260        if ( 'edit' == $context ) {
    11401261                if ( $prefixed ) {
     1262                        //duplicate hook
    11411263                        $value = apply_filters("edit_{$field}", $value, $user_id);
    11421264                } else {
     1265                        /**
     1266                         * Filter and sanitize the value of the prefixed field (for editing).
     1267                         *
     1268                         * The dynamic portion of the hook name, $field, refers to the prefixed
     1269                         * user field being filtered, such as 'user_login', 'user_email',
     1270                         * 'first_name', etc. 
     1271                         *
     1272                         * @since 2.9.0
     1273                         *
     1274                         * @param mixed $value   Value of the prefixed user field.
     1275                         * @param int   $user_id The user ID.
     1276                         */
    11431277                        $value = apply_filters("edit_user_{$field}", $value, $user_id);
    11441278                }
    11451279
    … … function sanitize_user_field($field, $value, $user_id, $context) {  
    11491283                        $value = esc_attr($value);
    11501284        } else if ( 'db' == $context ) {
    11511285                if ( $prefixed ) {
     1286                        //Dupicate hook
    11521287                        $value = apply_filters("pre_{$field}", $value);
    11531288                } else {
     1289                        /**
     1290                         * Filter and sanitize the value of the prefixed field (for database use).
     1291                         *
     1292                         * The dynamic portion of the hook name, $field, refers to the prefixed
     1293                         * user field being filtered, such as 'user_login', 'user_email',
     1294                         * 'first_name', etc.
     1295                         *
     1296                         * @since 2.9.0
     1297                         *
     1298                         * @param mixed $value Value of the prefixed user field.
     1299                         */
    11541300                        $value = apply_filters("pre_user_{$field}", $value);
    11551301                }
    11561302        } else {
    11571303                // Use display filters by default.
    1158                 if ( $prefixed )
     1304                if ( $prefixed ){
     1305                        //Duplicate hook
    11591306                        $value = apply_filters($field, $value, $user_id, $context);
    1160                 else
     1307                }else{
     1308                        /**
     1309                         * Filter and sanitize the value of the prefixed field (for other contexts).
     1310                         *
     1311                         * The dynamic portion of the hook name, $field, refers to the prefixed
     1312                         * user field being filtered, such as 'user_login', 'user_email',
     1313                         * 'first_name', etc.
     1314                         *
     1315                         * @since 2.9.0
     1316                         *
     1317                         * @param mixed  $value   The user object value to sanitize.
     1318                         * @param int    $user_id The User ID.
     1319                         * @param string $context The context to filter for.
     1320                         */
    11611321                        $value = apply_filters("user_{$field}", $value, $user_id, $context);
     1322                }
    11621323        }
    11631324
    11641325        if ( 'user_url' == $field )
    … … function email_exists( $email ) {  
    12501411function validate_username( $username ) {
    12511412        $sanitized = sanitize_user( $username, true );
    12521413        $valid = ( $sanitized == $username );
     1414        /**
     1415         * Filters whether the provided username is valid or not.
     1416         *
     1417         * @since 2.0.11
     1418         *
     1419         * @param bool   $valid    Whether username given is valid.
     1420         * @param string $username The username to check.
     1421         */
    12531422        return apply_filters( 'validate_username', $valid, $username );
    12541423}
    12551424
    … … function wp_insert_user( $userdata ) {  
    13211490        }
    13221491
    13231492        $user_login = sanitize_user($user_login, true);
     1493        /**
     1494         * Filters the username after it has been sanitized, but before the user is created or updated.
     1495         *
     1496         * This hook is called before the user is created or updated.
     1497         *
     1498         * @since 2.0.11
     1499         *
     1500         * @param string $user_login The username after it has been sanitized.
     1501         */
    13241502        $user_login = apply_filters('pre_user_login', $user_login);
    13251503
    13261504        //Remove any non-printable chars from the login string to see if we have ended up with an empty username
    … … function wp_insert_user( $userdata ) {  
    13341512
    13351513        if ( empty($user_nicename) )
    13361514                $user_nicename = sanitize_title( $user_login );
     1515       
     1516        /**
     1517         * Filters the user's nicename before the user is created or updated.
     1518         *
     1519         * This hook is called before the user is created or updated.
     1520         *
     1521         * @since 2.0.11
     1522         *
     1523         * @param string $user_nicename The user's nicename.
     1524         */
    13371525        $user_nicename = apply_filters('pre_user_nicename', $user_nicename);
    13381526
    13391527        if ( empty($user_url) )
    13401528                $user_url = '';
     1529       
     1530        /**
     1531         * Filters the user's url before the user is created or updated.
     1532         *
     1533         * @since 2.0.11
     1534         *
     1535         * @param string $user_url The user's url.
     1536         */
    13411537        $user_url = apply_filters('pre_user_url', $user_url);
    13421538
    13431539        if ( empty($user_email) )
    13441540                $user_email = '';
     1541       
     1542        /**
     1543         * Filters the user's email before the user is created or updated.
     1544         *
     1545         * @since 2.0.11
     1546         *
     1547         * @param string $user_email The user's email.
     1548         */
    13451549        $user_email = apply_filters('pre_user_email', $user_email);
    13461550
    13471551        if ( !$update && ! defined( 'WP_IMPORTING' ) && email_exists($user_email) )
    … … function wp_insert_user( $userdata ) {  
    13491553
    13501554        if ( empty($nickname) )
    13511555                $nickname = $user_login;
     1556       
     1557        /**
     1558         * Filters the user's nickname before the user is created or updated.
     1559         *
     1560         * @since 2.0.11
     1561         *
     1562         * @param string $nickname The user's nickname.
     1563         */
    13521564        $nickname = apply_filters('pre_user_nickname', $nickname);
    13531565
    13541566        if ( empty($first_name) )
    13551567                $first_name = '';
     1568       
     1569        /**
     1570         * Filters the user's first name before the user is created or updated.
     1571         *
     1572         * @since 2.0.11
     1573         *
     1574         * @param string $first_name The user's first name.
     1575         */
    13561576        $first_name = apply_filters('pre_user_first_name', $first_name);
    13571577
    13581578        if ( empty($last_name) )
    13591579                $last_name = '';
     1580       
     1581        /**
     1582         * Filters the user's last name before the user is created or updated.
     1583         *
     1584         * @since 2.0.11
     1585         *
     1586         * @param string $last_name The user's last name.
     1587         */
    13601588        $last_name = apply_filters('pre_user_last_name', $last_name);
    13611589
    13621590        if ( empty( $display_name ) ) {
    … … function wp_insert_user( $userdata ) {  
    13721600                else
    13731601                        $display_name = $user_login;
    13741602        }
     1603       
     1604        /**
     1605         * Filters the user's display name before the user is created or updated.
     1606         *
     1607         * @since 2.0.11
     1608         *
     1609         * @param string $display_name The user's display name.
     1610         */
    13751611        $display_name = apply_filters( 'pre_user_display_name', $display_name );
    13761612
    13771613        if ( empty($description) )
    13781614                $description = '';
     1615       
     1616        /**
     1617         * Filters the user's description before the user is created or updated.
     1618         *
     1619         * @since 2.0.11
     1620         *
     1621         * @param string $description The user's description.
     1622         */
    13791623        $description = apply_filters('pre_user_description', $description);
    13801624
    13811625        if ( empty($rich_editing) )
    … … function wp_insert_user( $userdata ) {  
    14351679        wp_cache_delete($user_id, 'users');
    14361680        wp_cache_delete($user_login, 'userlogins');
    14371681
    1438         if ( $update )
     1682        if ( $update ){
     1683                /**
     1684                 * Triggered after the user is updated.
     1685                 *
     1686                 * @since 2.0.0
     1687                 *
     1688                 * @param int    $user_id       The user ID.
     1689                 * @param object $old_user_data User's data prior to update as a raw object.
     1690                 */
    14391691                do_action('profile_update', $user_id, $old_user_data);
    1440         else
     1692        }else{
     1693                /**
     1694                 * Triggered after the user is created.
     1695                 *
     1696                 * @since 1.5.2
     1697                 *
     1698                 * @param int $user_id The user ID
     1699                 */
    14411700                do_action('user_register', $user_id);
     1701        }
    14421702
    14431703        return $user_id;
    14441704}
    … … function check_password_reset_key($key, $login) {  
    16481908 * @param string $new_pass New password for the user in plaintext
    16491909 */
    16501910function reset_password( $user, $new_pass ) {
     1911       
     1912        /**
     1913         * Triggered before the user's password is reset to $new_pass.
     1914         *
     1915         * @since Unknown
     1916         *
     1917         * @param int    $user_id       The user ID.
     1918         * @param object $old_user_data User's data prior to update as a raw object.
     1919         */
    16511920        do_action( 'password_reset', $user, $new_pass );
    1652 
     1921        //@since is uknown but exists before 1.5
    16531922        wp_set_password( $new_pass, $user->ID );
    16541923        update_user_option( $user->ID, 'default_password_nag', false, true );
    16551924
    … … function register_new_user( $user_login, $user_email ) {  
    16671936        $errors = new WP_Error();
    16681937
    16691938        $sanitized_user_login = sanitize_user( $user_login );
     1939        /**
     1940         * Filters the email address of a user being registered.
     1941         *
     1942         * This hooks is triggered before the user is created.
     1943         *
     1944         * @since 2.1.0
     1945         *
     1946         * @param string $user_email The email of the new user.
     1947         */
    16701948        $user_email = apply_filters( 'user_registration_email', $user_email );
    16711949
    16721950        // Check the username
    … … function register_new_user( $user_login, $user_email ) {  
    16891967                $errors->add( 'email_exists', __( '<strong>ERROR</strong>: This email is already registered, please choose another one.' ) );
    16901968        }
    16911969
     1970        /**
     1971         * Triggered when registration form data is submitted, and before the user has been created.
     1972         *
     1973         * @since 2.1.0
     1974         *
     1975         * @param string   $sanitized_user_login The submitted username after sanitization.
     1976         * @param string   $user_email           The submitted email.
     1977         * @param WP_Error $errors               Contains any errors with the submitted username and
     1978         *                                       email (e.g. invalid, already exists).
     1979         */
    16921980        do_action( 'register_post', $sanitized_user_login, $user_email, $errors );
    16931981
     1982        /**
     1983         * Filters the errors encountered when a new user is beng registerered.
     1984         *
     1985         * The filtered WP_Error object may, for example, contain errors for an invalid
     1986         * or existing username or email. A WP_Error object should always returned, but
     1987         * may or may not contain errors.
     1988         *
     1989         * If any errors are present in $errors, this will abort the user's registration.
     1990         *
     1991         * @since 2.1.0
     1992         *
     1993         * @param WP_Error $errors               A WP_Error object which contains any errors encountered during registration.
     1994         * @param string   $sanitized_user_login The user's username after it has been sanitized.
     1995         * @param string   $user_email           The user's email.
     1996         */
    16941997        $errors = apply_filters( 'registration_errors', $errors, $sanitized_user_login, $user_email );
    16951998
    16961999        if ( $errors->get_error_code() )