WordPress.org
Get WordPress

Make WordPress Core

Ticket #25533: 25533.3.diff

File 25533.3.diff, 16.5 KB (added by DrewAPicture, 13 years ago)

3rd pass

  • src/wp-includes/user.php

     
    3838                $credentials['remember'] = false;
    3939
    4040        // TODO do we deprecate the wp_authentication action?
    41         do_action_ref_array('wp_authenticate', array(&$credentials['user_login'], &$credentials['user_password']));
     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    Username, passed by reference.
     49         * @param string $user_password User password, passed by reference.
     50         */
     51        do_action_ref_array( 'wp_authenticate', array( &$credentials['user_login'], &$credentials['user_password'] ) );
    4252
    4353        if ( '' === $secure_cookie )
    4454                $secure_cookie = is_ssl();
    4555
    46         $secure_cookie = apply_filters('secure_signon_cookie', $secure_cookie, $credentials);
     56        /**
     57         * Filter whether to use a secure sign-on cookie.
     58         *
     59         * @since 3.1.0
     60         *
     61         * @param bool  $secure_cookie Whether to use a secure sign-on cookie.
     62         * @param array $args {
     63         *     Array of entered sign-on data.
     64         *
     65         *     @type string $user_login    Username.
     66         *     @type string $user_password Password entered.
     67         *     @type bool   $remember      Whether to 'remember' the user. Increases the time
     68         *                                 that the cookie will be kept. Default false.
     69         * }
     70         */
     71        $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
    4974        $auth_secure_cookie = $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        /**
     91         * Triggered after the user has successfully logged in.
     92         *
     93         * @since 1.5.2
     94         *
     95         * @param string  $user_login Username.
     96         * @param WP_User $user       WP_User object of the logged-in user.
     97         */
     98        do_action( 'wp_login', $user->user_login, $user );
    6599        return $user;
    66100}
    67101
    … …  
    92126        if ( !$user )
    93127                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() ) );
    94128
     129        /**
     130         * Filter whether the given user can be authenticated with the provided $password.
     131         *
     132         * @since 2.5.0
     133         *
     134         * @param WP_User|WP_Error $user     WP_User object or WP_Error object if a previous
     135         *                                   callback failed authentication.
     136         * @param string           $password The password to check against the user.
     137         */
    95138        $user = apply_filters('wp_authenticate_user', $user, $password);
    96139        if ( is_wp_error($user) )
    97140                return $user;
    … …  
    138181 */
    139182function wp_authenticate_spam_check( $user ) {
    140183        if ( $user && is_a( $user, 'WP_User' ) && is_multisite() ) {
     184                /**
     185                 * Filter whether the user has been marked as a spammer.
     186                 *
     187                 * @since 3.7.0
     188                 *
     189                 * @param bool    $spammed Whether the user is considered spam.
     190                 * @param WP_User $user    The user to check against.
     191                 */
    141192                $spammed = apply_filters( 'check_is_user_spammed', is_user_spammy(), $user );
    142193
    143194                if ( $spammed )
    … …  
    162213
    163214        $count = $wpdb->get_var( "SELECT COUNT(*) FROM $wpdb->posts $where" );
    164215
    165         return apply_filters('get_usernumposts', $count, $userid);
     216        /**
     217         * Filter the number of posts a user has written.
     218         *
     219         * @since 2.7.0
     220         *
     221         * @param int $count  The user's post count.
     222         * @param int $userid User ID.
     223         */
     224        return apply_filters( 'get_usernumposts', $count, $userid );
    166225}
    167226
    168227/**
    … …  
    258317        else
    259318                $result = false;
    260319
    261         return apply_filters("get_user_option_{$option}", $result, $option, $user);
     320        /**
     321         * Filter a specific user option value.
     322         *
     323         * The dynamic portion of the hook name, $option, refers to
     324         * the user option name.
     325         *
     326         * @since 2.5.0
     327         *
     328         * @param mixed   $result Value for the user's option.
     329         * @param string  $option Name of the option being retrieved.
     330         * @param WP_User $user   WP_User object of the user whose option is being retrieved.
     331         */
     332        return apply_filters( "get_user_option_{$option}", $result, $option, $user );
    262333}
    263334
    264335/**
    … …  
    496567                                        $search_columns = array('user_login', 'user_nicename');
    497568                        }
    498569
     570                        /**
     571                         * Filter the columns to search in a WP_User_Query search.
     572                         *
     573                         * The default columns depend on the search term and include 'user_email',
     574                         * 'user_login', 'ID', 'user_url' and 'user_nicename'.
     575                         *
     576                         * @since 3.6.0
     577                         *
     578                         * @param array         $search_columns Array of column names to be searched.
     579                         * @param string        $search         The text being searched.
     580                         * @param WP_User_Query $this           The current WP_User_Query instance.
     581                         */
    499582                        $search_columns = apply_filters( 'user_search_columns', $search_columns, $search, $this );
    500583
    501584                        $this->query_where .= $this->get_search_sql( $search, $search_columns, $wild );
    … …  
    548631                        $this->query_where .= " AND $wpdb->users.ID NOT IN ($ids)";
    549632                }
    550633
     634                /**
     635                 * Fires after the WP_User_Query has been parsed and before
     636                 * the query is executed.
     637                 *
     638                 * The passed WP_User_Query object contains SQL parts formed
     639                 * from parsing the given query.
     640                 *
     641                 * @since 1.5.2
     642                 *
     643                 * @param WP_User_Query $this The current WP_User_Query instance,
     644                 *                            passed by reference.
     645                 */
    551646                do_action_ref_array( 'pre_user_query', array( &$this ) );
    552647        }
    553648
    … …  
    568663                        $this->results = $wpdb->get_col("SELECT $this->query_fields $this->query_from $this->query_where $this->query_orderby $this->query_limit");
    569664                }
    570665
     666                /**
     667                 * Filter SELECT_FOUND_ROWS value for the current WP_User_Query instance.
     668                 *
     669                 * @since 3.2.0
     670                 *
     671                 * @global wpdb $wpdb WordPress database object.
     672                 *
     673                 * @param string $sql The SELECT_FOUND_ROWS() value for the current WP_User_Query.
     674                 */
    571675                if ( isset( $qv['count_total'] ) && $qv['count_total'] )
    572676                        $this->total_users = $wpdb->get_var( apply_filters( 'found_users_query', 'SELECT FOUND_ROWS()' ) );
    573677
    … …  
    776880                }
    777881        }
    778882
     883        /**
     884         * Filter list of blogs a user belongs to.
     885         *
     886         * @since 3.1.0
     887         *
     888         * @param array $blogs   An array of blog objects belonging to the user.
     889         * @param int   $user_id User ID.
     890         * @param bool  $all     Whether the returned blogs array should contain all blog, including
     891         *                       those marked 'deleted', 'archived', or 'spam'. Default false.
     892         */
    779893        return apply_filters( 'get_blogs_of_user', $blogs, $user_id, $all );
    780894}
    781895
    … …  
    10941208
    10951209                $output .= "</select>";
    10961210        }
     1211       
     1212        /**
     1213         * Filter the wp_dropdown_users() HTML output.
     1214         *
     1215         * @since 2.3.0
     1216         *
     1217         * @param string $output HTML output generated by wp_dropdown_users().
     1218         */
     1219        $output = apply_filters( 'wp_dropdown_users', $output );
    10971220
    1098         $output = apply_filters('wp_dropdown_users', $output);
    1099 
    11001221        if ( $echo )
    11011222                echo $output;
    11021223
    … …  
    11401261
    11411262        if ( 'edit' == $context ) {
    11421263                if ( $prefixed ) {
    1143                         $value = apply_filters("edit_{$field}", $value, $user_id);
     1264                        /** This filter is documented in wp-includes/post.php */
     1265                        $value = apply_filters( "edit_{$field}", $value, $user_id );
    11441266                } else {
     1267                        /**
     1268                         * Filter a user field value in the 'edit' context.
     1269                         *
     1270                         * The dynamic portion of the hook name, $field, refers to the prefixed
     1271                         * user field being filtered, such as 'user_login', 'user_email',
     1272                         * 'first_name', etc. 
     1273                         *
     1274                         * @since 2.9.0
     1275                         *
     1276                         * @param mixed $value   Value of the prefixed user field.
     1277                         * @param int   $user_id User ID.
     1278                         */
    11451279                        $value = apply_filters("edit_user_{$field}", $value, $user_id);
    11461280                }
    11471281
    … …  
    11511285                        $value = esc_attr($value);
    11521286        } else if ( 'db' == $context ) {
    11531287                if ( $prefixed ) {
    1154                         $value = apply_filters("pre_{$field}", $value);
     1288                        /** This filter is documented in wp-includes/post.php */
     1289                        $value = apply_filters( "pre_{$field}", $value );
    11551290                } else {
    1156                         $value = apply_filters("pre_user_{$field}", $value);
     1291                        /**
     1292                         * Filter the value of a user field in the 'db' context.
     1293                         *
     1294                         * The dynamic portion of the hook name, $field, refers to the prefixed
     1295                         * user field being filtered, such as 'user_login', 'user_email',
     1296                         * 'first_name', etc.
     1297                         *
     1298                         * @since 2.9.0
     1299                         *
     1300                         * @param mixed $value Value of the prefixed user field.
     1301                         */
     1302                        $value = apply_filters( "pre_user_{$field}", $value );
    11571303                }
    11581304        } else {
    11591305                // Use display filters by default.
    1160                 if ( $prefixed )
    1161                         $value = apply_filters($field, $value, $user_id, $context);
    1162                 else
     1306                if ( $prefixed ){
     1307                        /** This filter is documented in wp-includes/post.php */
     1308                        $value = apply_filters( $field, $value, $user_id, $context );
     1309                }else{
     1310                        /**
     1311                         * Filter the value of a user field in a standard context.
     1312                         *
     1313                         * The dynamic portion of the hook name, $field, refers to the prefixed
     1314                         * user field being filtered, such as 'user_login', 'user_email',
     1315                         * 'first_name', etc.
     1316                         *
     1317                         * @since 2.9.0
     1318                         *
     1319                         * @param mixed  $value   The user object value to sanitize.
     1320                         * @param int    $user_id User ID.
     1321                         * @param string $context The context to filter within.
     1322                         */
    11631323                        $value = apply_filters("user_{$field}", $value, $user_id, $context);
     1324                }
    11641325        }
    11651326
    11661327        if ( 'user_url' == $field )
    … …  
    12521413function validate_username( $username ) {
    12531414        $sanitized = sanitize_user( $username, true );
    12541415        $valid = ( $sanitized == $username );
     1416        /**
     1417         * Filter whether the provided username is valid or not.
     1418         *
     1419         * @since 2.0.11
     1420         *
     1421         * @param bool   $valid    Whether username given is valid.
     1422         * @param string $username The username to check.
     1423         */
    12551424        return apply_filters( 'validate_username', $valid, $username );
    12561425}
    12571426
    … …  
    13171486        }
    13181487
    13191488        $user_login = sanitize_user($user_login, true);
    1320         $user_login = apply_filters('pre_user_login', $user_login);
     1489        /**
     1490         * Filter a username after it has been sanitized, but before
     1491         * the user is created or updated.
     1492         *
     1493         * This hook is called before the user is created or updated.
     1494         *
     1495         * @since 2.0.11
     1496         *
     1497         * @param string $user_login The username after it has been sanitized.
     1498         */
     1499        $user_login = apply_filters( 'pre_user_login', $user_login );
    13211500
    13221501        //Remove any non-printable chars from the login string to see if we have ended up with an empty username
    13231502        $user_login = trim($user_login);
    … …  
    13301509
    13311510        if ( empty($user_nicename) )
    13321511                $user_nicename = sanitize_title( $user_login );
    1333         $user_nicename = apply_filters('pre_user_nicename', $user_nicename);
     1512       
     1513        /**
     1514         * Filter a user's nicename before the user is created or updated.
     1515         *
     1516         * This hook is called before the user is created or updated.
     1517         *
     1518         * @since 2.0.11
     1519         *
     1520         * @param string $user_nicename The user's nicename.
     1521         */
     1522        $user_nicename = apply_filters( 'pre_user_nicename', $user_nicename );
    13341523
    13351524        if ( empty($user_url) )
    13361525                $user_url = '';
    1337         $user_url = apply_filters('pre_user_url', $user_url);
     1526       
     1527        /**
     1528         * Filter a user's URL before the user is created or updated.
     1529         *
     1530         * @since 2.0.11
     1531         *
     1532         * @param string $user_url The user's URL.
     1533         */
     1534        $user_url = apply_filters( 'pre_user_url', $user_url );
    13381535
    13391536        if ( empty($user_email) )
    13401537                $user_email = '';
    1341         $user_email = apply_filters('pre_user_email', $user_email);
     1538       
     1539        /**
     1540         * Filter a user's email before the user is created or updated.
     1541         *
     1542         * @since 2.0.11
     1543         *
     1544         * @param string $user_email The user's email.
     1545         */
     1546        $user_email = apply_filters( 'pre_user_email', $user_email );
    13421547
    13431548        if ( !$update && ! defined( 'WP_IMPORTING' ) && email_exists($user_email) )
    13441549                return new WP_Error( 'existing_user_email', __( 'Sorry, that email address is already used!' ) );
    13451550
    13461551        if ( empty($nickname) )
    13471552                $nickname = $user_login;
    1348         $nickname = apply_filters('pre_user_nickname', $nickname);
     1553       
     1554        /**
     1555         * Filter a user's nickname before the user is created or updated.
     1556         *
     1557         * @since 2.0.11
     1558         *
     1559         * @param string $nickname The user's nickname.
     1560         */
     1561        $nickname = apply_filters( 'pre_user_nickname', $nickname );
    13491562
    13501563        if ( empty($first_name) )
    13511564                $first_name = '';
    1352         $first_name = apply_filters('pre_user_first_name', $first_name);
     1565       
     1566        /**
     1567         * Filter a user's first name before the user is created or updated.
     1568         *
     1569         * @since 2.0.11
     1570         *
     1571         * @param string $first_name The user's first name.
     1572         */
     1573        $first_name = apply_filters( 'pre_user_first_name', $first_name );
    13531574
    13541575        if ( empty($last_name) )
    13551576                $last_name = '';
    1356         $last_name = apply_filters('pre_user_last_name', $last_name);
     1577       
     1578        /**
     1579         * Filter a user's last name before the user is created or updated.
     1580         *
     1581         * @since 2.0.11
     1582         *
     1583         * @param string $last_name The user's last name.
     1584         */
     1585        $last_name = apply_filters( 'pre_user_last_name', $last_name );
    13571586
    13581587        if ( empty( $display_name ) ) {
    13591588                if ( $update )
    … …  
    13681597                else
    13691598                        $display_name = $user_login;
    13701599        }
     1600       
     1601        /**
     1602         * Filter a user's display name before the user is created or updated.
     1603         *
     1604         * @since 2.0.11
     1605         *
     1606         * @param string $display_name The user's display name.
     1607         */
    13711608        $display_name = apply_filters( 'pre_user_display_name', $display_name );
    13721609
    13731610        if ( empty($description) )
    13741611                $description = '';
    1375         $description = apply_filters('pre_user_description', $description);
     1612       
     1613        /**
     1614         * Filter a user's description before the user is created or updated.
     1615         *
     1616         * @since 2.0.11
     1617         *
     1618         * @param string $description The user's description.
     1619         */
     1620        $description = apply_filters( 'pre_user_description', $description );
    13761621
    13771622        if ( empty($rich_editing) )
    13781623                $rich_editing = 'true';
    … …  
    14311676        wp_cache_delete($user_id, 'users');
    14321677        wp_cache_delete($user_login, 'userlogins');
    14331678
    1434         if ( $update )
     1679        if ( $update ) {
     1680                /**
     1681                 * Fires immediately after an existing user is updated.
     1682                 *
     1683                 * @since 2.0.0
     1684                 *
     1685                 * @param int    $user_id       User ID.
     1686                 * @param object $old_user_data Object containing user's data prior to update.
     1687                 */
    14351688                do_action('profile_update', $user_id, $old_user_data);
    1436         else
    1437                 do_action('user_register', $user_id);
     1689        } else {
     1690                /**
     1691                 * Fires immediately after a new user is registered.
     1692                 *
     1693                 * @since 1.5.2
     1694                 *
     1695                 * @param int $user_id User ID.
     1696                 */
     1697                do_action( 'user_register', $user_id );
     1698        }
    14381699
    14391700        return $user_id;
    14401701}
    … …  
    16431904 * @param string $new_pass New password for the user in plaintext
    16441905 */
    16451906function reset_password( $user, $new_pass ) {
     1907       
     1908        /**
     1909         * Fires before the user's password is reset.
     1910         *
     1911         * @since Unknown
     1912         *
     1913         * @param int    $user_id       User ID.
     1914         * @param object $old_user_data User's data prior to update as a raw object.
     1915         */
    16461916        do_action( 'password_reset', $user, $new_pass );
    16471917
    16481918        wp_set_password( $new_pass, $user->ID );
    … …  
    16621932        $errors = new WP_Error();
    16631933
    16641934        $sanitized_user_login = sanitize_user( $user_login );
     1935        /**
     1936         * Filter the email address of a user being registered.
     1937         *
     1938         * This hooks is triggered before the user is created.
     1939         *
     1940         * @since 2.1.0
     1941         *
     1942         * @param string $user_email The email of the new user.
     1943         */
    16651944        $user_email = apply_filters( 'user_registration_email', $user_email );
    16661945
    16671946        // Check the username
    … …  
    16841963                $errors->add( 'email_exists', __( '<strong>ERROR</strong>: This email is already registered, please choose another one.' ) );
    16851964        }
    16861965
     1966        /**
     1967         * FIRES when registration form data is submitted, and before the user has been created.
     1968         *
     1969         * @since 2.1.0
     1970         *
     1971         * @param string   $sanitized_user_login The submitted username after being sanitized.
     1972         * @param string   $user_email           The submitted email.
     1973         * @param WP_Error $errors               Contains any errors with the submitted username and
     1974         *                                       email (e.g. invalid, already exists).
     1975         */
    16871976        do_action( 'register_post', $sanitized_user_login, $user_email, $errors );
    16881977
     1978        /**
     1979         * Filter the errors encountered when a new user is beng registerered.
     1980         *
     1981         * The filtered WP_Error object may, for example, contain errors for an invalid
     1982         * or existing username or email. A WP_Error object should always returned, but
     1983         * may or may not contain errors.
     1984         *
     1985         * If any errors are present in $errors, this will abort the user's registration.
     1986         *
     1987         * @since 2.1.0
     1988         *
     1989         * @param WP_Error $errors               A WP_Error object containing any errors encountered
     1990         *                                       during registration.
     1991         * @param string   $sanitized_user_login User's username after it has been sanitized.
     1992         * @param string   $user_email           User's email.
     1993         */
    16891994        $errors = apply_filters( 'registration_errors', $errors, $sanitized_user_login, $user_email );
    16901995
    16911996        if ( $errors->get_error_code() )