WordPress.org
Get WordPress

Make WordPress Core

Ticket #26888: 26888.3.diff

File 26888.3.diff, 26.3 KB (added by DrewAPicture, 11 years ago)

Final pass.

  • src/wp-includes/pluggable.php

     
    1818 *
    1919 * @since 2.0.3
    2020 * @global object $current_user The current user object which holds the user data.
    21  * @uses do_action() Calls 'set_current_user' hook after setting the current user.
    2221 *
    2322 * @param int $id User ID
    2423 * @param string $name User's username
    … …  
    3433
    3534        setup_userdata( $current_user->ID );
    3635
    37         do_action('set_current_user');
     36        /**
     37         * Fires after the current user is set.
     38         *
     39         * @since 2.0.1
     40         */
     41        do_action( 'set_current_user' );
    3842
    3943        return $current_user;
    4044}
    … …  
    105109         *
    106110         * @since 3.9.0
    107111         *
    108          * @param int|boolean $user_id User ID if determined, or false otherwise.
     112         * @param int|bool $user_id User ID if determined, or false otherwise.
    109113         */
    110114        $user_id = apply_filters( 'determine_current_user', false );
    111115        if ( ! $user_id ) {
    … …  
    204208 * be set using the 'wp_mail_charset' filter.
    205209 *
    206210 * @since 1.2.1
    207  * @uses apply_filters() Calls 'wp_mail' hook on an array of all of the parameters.
    208  * @uses apply_filters() Calls 'wp_mail_from' hook to get the from email address.
    209  * @uses apply_filters() Calls 'wp_mail_from_name' hook to get the from address name.
    210  * @uses apply_filters() Calls 'wp_mail_content_type' hook to get the email content type.
    211  * @uses apply_filters() Calls 'wp_mail_charset' hook to get the email charset
    212  * @uses do_action_ref_array() Calls 'phpmailer_init' hook on the reference to
    213  *              phpmailer object.
     211 *
    214212 * @uses PHPMailer
    215213 *
    216214 * @param string|array $to Array or comma-separated list of email addresses to send message.
    … …  
    222220 */
    223221function wp_mail( $to, $subject, $message, $headers = '', $attachments = array() ) {
    224222        // Compact the input, apply the filters, and extract them back out
     223
     224        /**
     225         * Filter the wp_mail() arguments.
     226         *
     227         * @since 2.2.0
     228         *
     229         * @param array $args A compacted array of wp_mail() arguments, including the "to" email,
     230         *                    subject, message, headers, and attachments values.
     231         */
    225232        extract( apply_filters( 'wp_mail', compact( 'to', 'subject', 'message', 'headers', 'attachments' ) ) );
    226233
    227234        if ( !is_array($attachments) )
    … …  
    342349                $from_email = 'wordpress@' . $sitename;
    343350        }
    344351
    345         // Plugin authors can override the potentially troublesome default
    346         $phpmailer->From     = apply_filters( 'wp_mail_from'     , $from_email );
    347         $phpmailer->FromName = apply_filters( 'wp_mail_from_name', $from_name  );
     352        /**
     353         * Filter the email address to send from.
     354         *
     355         * @since 2.2.0
     356         *
     357         * @param string $from_email Email address to send from.
     358         */
     359        $phpmailer->From = apply_filters( 'wp_mail_from', $from_email );
    348360
     361        /**
     362         * Filter the name to associate with the "from" email address.
     363         *
     364         * @since 2.3.0
     365         *
     366         * @param string $from_name Name associated with the "from" email address.
     367         */
     368        $phpmailer->FromName = apply_filters( 'wp_mail_from_name', $from_name );
     369
    349370        // Set destination addresses
    350371        if ( !is_array( $to ) )
    351372                $to = explode( ',', $to );
    … …  
    415436        if ( !isset( $content_type ) )
    416437                $content_type = 'text/plain';
    417438
     439        /**
     440         * Filter the wp_mail() content type.
     441         *
     442         * @since 2.3.0
     443         *
     444         * @param string $content_type Default wp_mail() content type.
     445         */
    418446        $content_type = apply_filters( 'wp_mail_content_type', $content_type );
    419447
    420448        $phpmailer->ContentType = $content_type;
    … …  
    428456                $charset = get_bloginfo( 'charset' );
    429457
    430458        // Set the content-type and charset
     459
     460        /**
     461         * Filter the default wp_mail() charset.
     462         *
     463         * @since 2.3.0
     464         *
     465         * @param string $charset Default email charset.
     466         */
    431467        $phpmailer->CharSet = apply_filters( 'wp_mail_charset', $charset );
    432468
    433469        // Set custom headers
    … …  
    450486                }
    451487        }
    452488
     489        /**
     490         * Fires after PHPMailer is initialized.
     491         *
     492         * @since 2.2.0
     493         *
     494         * @param PHPMailer &$phpmailer The PHPMailer instance, passed by reference.
     495         */
    453496        do_action_ref_array( 'phpmailer_init', array( &$phpmailer ) );
    454497
    455498        // Send!
    … …  
    475518        $username = sanitize_user($username);
    476519        $password = trim($password);
    477520
    478         $user = apply_filters('authenticate', null, $username, $password);
     521        /**
     522         * Filter the user to authenticate.
     523         *
     524         * If a non-null value is passed, the filter will effectively short-circuit
     525         * authentication, returning an error instead.
     526         *
     527         * @since 2.8.0
     528         *
     529         * @param null|WP_User $user     User to authenticate.
     530         * @param string       $username User login.
     531         * @param string       $password User password
     532         */
     533        $user = apply_filters( 'authenticate', null, $username, $password );
    479534
    480535        if ( $user == null ) {
    481536                // TODO what should the error message be? (Or would these even happen?)
    … …  
    486541        $ignore_codes = array('empty_username', 'empty_password');
    487542
    488543        if (is_wp_error($user) && !in_array($user->get_error_code(), $ignore_codes) ) {
    489                 do_action('wp_login_failed', $username);
     544                /**
     545                 * Fires after a user login has failed.
     546                 *
     547                 * @since 2.5.0
     548                 *
     549                 * @param string $username User login.
     550                 */
     551                do_action( 'wp_login_failed', $username );
    490552        }
    491553
    492554        return $user;
    … …  
    501563 */
    502564function wp_logout() {
    503565        wp_clear_auth_cookie();
    504         do_action('wp_logout');
     566
     567        /**
     568         * Fires after a user is logged-out.
     569         *
     570         * @since 1.5.0
     571         */
     572        do_action( 'wp_logout' );
    505573}
    506574endif;
    507575
    … …  
    523591 */
    524592function wp_validate_auth_cookie($cookie = '', $scheme = '') {
    525593        if ( ! $cookie_elements = wp_parse_auth_cookie($cookie, $scheme) ) {
    526                 do_action('auth_cookie_malformed', $cookie, $scheme);
     594                /**
     595                 * Fires if an authentication cookie is malformed.
     596                 *
     597                 * @since 2.7.0
     598                 *
     599                 * @param string $cookie Malformed auth cookie.
     600                 * @param string $scheme Authentication scheme. Values include 'auth', 'secure_auth',
     601                 *                       or 'logged_in'.
     602                 */
     603                do_action( 'auth_cookie_malformed', $cookie, $scheme );
    527604                return false;
    528605        }
    529606
    … …  
    537614
    538615        // Quick check to see if an honest cookie has expired
    539616        if ( $expired < time() ) {
    540                 do_action('auth_cookie_expired', $cookie_elements);
     617                /**
     618                 * Fires once an authentication cookie has expired.
     619                 *
     620                 * @since 2.7.0
     621                 *
     622                 * @param array $cookie_elements An array of data for the authentication cookie.
     623                 */
     624                do_action( 'auth_cookie_expired', $cookie_elements );
    541625                return false;
    542626        }
    543627
    544628        $user = get_user_by('login', $username);
    545629        if ( ! $user ) {
    546                 do_action('auth_cookie_bad_username', $cookie_elements);
     630                /**
     631                 * Fires if a bad username is entered in the user authentication process.
     632                 *
     633                 * @since 2.7.0
     634                 *
     635                 * @param array $cookie_elements An array of data for the authentication cookie.
     636                 */
     637                do_action( 'auth_cookie_bad_username', $cookie_elements );
    547638                return false;
    548639        }
    549640
    … …  
    553644        $hash = hash_hmac('md5', $username . '|' . $expiration, $key);
    554645
    555646        if ( $hmac != $hash ) {
    556                 do_action('auth_cookie_bad_hash', $cookie_elements);
     647                /**
     648                 * Fires if a bad authentication cookie hash is encountered.
     649                 *
     650                 * @since 2.7.0
     651                 *
     652                 * @param array $cookie_elements An array of data for the authentication cookie.
     653                 */
     654                do_action( 'auth_cookie_bad_hash', $cookie_elements );
    557655                return false;
    558656        }
    559657
    560658        if ( $expiration < time() ) // AJAX/POST grace period set above
    561659                $GLOBALS['login_grace_period'] = 1;
    562660
    563         do_action('auth_cookie_valid', $cookie_elements, $user);
     661        /**
     662         * Fires once an authentication cookie has been validated.
     663         *
     664         * @since 2.7.0
     665         *
     666         * @param array   $cookie_elements An array of data for the authentication cookie.
     667         * @param WP_User $user            User object.
     668         */
     669        do_action( 'auth_cookie_valid', $cookie_elements, $user );
    564670
    565671        return $user->ID;
    566672}
    … …  
    572678 *
    573679 * @since 2.5.0
    574680 *
    575  * @uses apply_filters() Calls 'auth_cookie' hook on $cookie contents, User ID
    576  *              and expiration of cookie.
    577  *
    578681 * @param int $user_id User ID
    579682 * @param int $expiration Cookie expiration in seconds
    580683 * @param string $scheme Optional. The cookie scheme to use: auth, secure_auth, or logged_in
    … …  
    590693
    591694        $cookie = $user->user_login . '|' . $expiration . '|' . $hash;
    592695
    593         return apply_filters('auth_cookie', $cookie, $user_id, $expiration, $scheme);
     696        /**
     697         * Filter the authentication cookie.
     698         *
     699         * @since 2.5.0
     700         *
     701         * @param string $cookie     Authentication cookie.
     702         * @param int    $user_id    User ID.
     703         * @param int    $expiration Authentication cookie expiration in seconds.
     704         * @param string $scheme     Cookie scheme used. Accepts 'auth', 'secure_auth', or 'logged_in'.
     705         */
     706        return apply_filters( 'auth_cookie', $cookie, $user_id, $expiration, $scheme );
    594707}
    595708endif;
    596709
    … …  
    656769 */
    657770function wp_set_auth_cookie($user_id, $remember = false, $secure = '') {
    658771        if ( $remember ) {
    659                 $expiration = time() + apply_filters('auth_cookie_expiration', 14 * DAY_IN_SECONDS, $user_id, $remember);
    660                 // Ensure the browser will continue to send the cookie after the expiration time is reached.
    661                 // Needed for the login grace period in wp_validate_auth_cookie().
     772                /**
     773                 * Filter the duration of the authentication cookie expiration period.
     774                 *
     775                 * @since 2.8.0
     776                 *
     777                 * @param int  $length   Duration of the expiration period in seconds.
     778                 * @param int  $user_id  User ID.
     779                 * @param bool $remember Whether to remember the user login. Default false.
     780                 */
     781                $expiration = time() + apply_filters( 'auth_cookie_expiration', 14 * DAY_IN_SECONDS, $user_id, $remember );
     782
     783                /*
     784                 * Ensure the browser will continue to send the cookie after the expiration time is reached.
     785                 * Needed for the login grace period in wp_validate_auth_cookie().
     786                 */
    662787                $expire = $expiration + ( 12 * HOUR_IN_SECONDS );
    663788        } else {
    664                 $expiration = time() + apply_filters('auth_cookie_expiration', 2 * DAY_IN_SECONDS, $user_id, $remember);
     789                /** This filter is documented in wp-includes/pluggable.php */
     790                $expiration = time() + apply_filters( 'auth_cookie_expiration', 2 * DAY_IN_SECONDS, $user_id, $remember );
    665791                $expire = 0;
    666792        }
    667793
    668794        if ( '' === $secure )
    669795                $secure = is_ssl();
    670796
    671         $secure = apply_filters('secure_auth_cookie', $secure, $user_id);
    672         $secure_logged_in_cookie = apply_filters('secure_logged_in_cookie', false, $user_id, $secure);
     797        /**
     798         * Filter whether the connection is secure.
     799         *
     800         * @since 3.1.0
     801         *
     802         * @param bool $secure  Whether the connection is secure.
     803         * @param int  $user_id User ID.
     804         */
     805        $secure = apply_filters( 'secure_auth_cookie', $secure, $user_id );
    673806
     807        /**
     808         * Filter whether to use a secure cookie when logged-in.
     809         *
     810         * @since 3.1.0
     811         *
     812         * @param bool $cookie  Whether to use a secure cookie when logged-in.
     813         * @param int  $user_id User ID.
     814         * @param bool $secure  Whether the connection is secure.
     815         */
     816        $secure_logged_in_cookie = apply_filters( 'secure_logged_in_cookie', false, $user_id, $secure );
     817
    674818        if ( $secure ) {
    675819                $auth_cookie_name = SECURE_AUTH_COOKIE;
    676820                $scheme = 'secure_auth';
    … …  
    682826        $auth_cookie = wp_generate_auth_cookie($user_id, $expiration, $scheme);
    683827        $logged_in_cookie = wp_generate_auth_cookie($user_id, $expiration, 'logged_in');
    684828
    685         do_action('set_auth_cookie', $auth_cookie, $expire, $expiration, $user_id, $scheme);
    686         do_action('set_logged_in_cookie', $logged_in_cookie, $expire, $expiration, $user_id, 'logged_in');
     829        /**
     830         * Fires immediately before the authentication cookie is set.
     831         *
     832         * @since 2.5.0
     833         *
     834         * @param string $auth_cookie Authentication cookie.
     835         * @param int    $expire      Login grace period in seconds. Default 43,200 seconds, or 12 hours.
     836         * @param int    $expiration  Duration in seconds the authentication cookie should be valid.
     837         *                            Default 1,209,600 seconds, or 14 days.
     838         * @param int    $user_id     User ID.
     839         * @param string $scheme      Authentication scheme. Values include 'auth', 'secure_auth', or 'logged_in'.
     840         */
     841        do_action( 'set_auth_cookie', $auth_cookie, $expire, $expiration, $user_id, $scheme );
    687842
     843        /**
     844         * Fires immediately before the secure authentication cookie is set.
     845         *
     846         * @since 2.6.0
     847         *
     848         * @param string $logged_in_cookie The logged-in cookie.
     849         * @param int    $expire           Login grace period in seconds. Default 43,200 seconds, or 12 hours.
     850         * @param int    $expiration       Duration in seconds the authentication cookie should be valid.
     851         *                                 Default 1,209,600 seconds, or 14 days.
     852         * @param int    $user_id          User ID.
     853         * @param string $scheme           Authentication scheme. Default 'logged_in'.
     854         */
     855        do_action( 'set_logged_in_cookie', $logged_in_cookie, $expire, $expiration, $user_id, 'logged_in' );
     856
    688857        setcookie($auth_cookie_name, $auth_cookie, $expire, PLUGINS_COOKIE_PATH, COOKIE_DOMAIN, $secure, true);
    689858        setcookie($auth_cookie_name, $auth_cookie, $expire, ADMIN_COOKIE_PATH, COOKIE_DOMAIN, $secure, true);
    690859        setcookie(LOGGED_IN_COOKIE, $logged_in_cookie, $expire, COOKIEPATH, COOKIE_DOMAIN, $secure_logged_in_cookie, true);
    … …  
    700869 * @since 2.5.0
    701870 */
    702871function wp_clear_auth_cookie() {
    703         do_action('clear_auth_cookie');
     872        /**
     873         * Fires just before the authentication cookies are cleared.
     874         *
     875         * @since 2.7.0
     876         */
     877        do_action( 'clear_auth_cookie' );
    704878
    705879        setcookie( AUTH_COOKIE,        ' ', time() - YEAR_IN_SECONDS, ADMIN_COOKIE_PATH,   COOKIE_DOMAIN );
    706880        setcookie( SECURE_AUTH_COOKIE, ' ', time() - YEAR_IN_SECONDS, ADMIN_COOKIE_PATH,   COOKIE_DOMAIN );
    … …  
    752926
    753927        $secure = ( is_ssl() || force_ssl_admin() );
    754928
    755         $secure = apply_filters('secure_auth_redirect', $secure);
     929        /**
     930         * Filter whether to use a secure authentication redirect.
     931         *
     932         * @since 3.1.0
     933         *
     934         * @param bool $secure Whether to use a secure authentication redirect. Default false.
     935         */
     936        $secure = apply_filters( 'secure_auth_redirect', $secure );
    756937
    757938        // If https is required and request is http, redirect
    758939        if ( $secure && !is_ssl() && false !== strpos($_SERVER['REQUEST_URI'], 'wp-admin') ) {
    … …  
    765946                }
    766947        }
    767948
    768         if ( is_user_admin() )
     949        if ( is_user_admin() ) {
    769950                $scheme = 'logged_in';
    770         else
     951        } else {
     952                /**
     953                 * Filter the authentication redirect scheme.
     954                 *
     955                 * @since 2.9.0
     956                 *
     957                 * @param string $scheme Authentication redirect scheme. Default empty.
     958                 */
    771959                $scheme = apply_filters( 'auth_redirect_scheme', '' );
     960        }
    772961
    773962        if ( $user_id = wp_validate_auth_cookie( '',  $scheme) ) {
    774                 do_action('auth_redirect', $user_id);
     963                /**
     964                 * Fires before the authentication redirect.
     965                 *
     966                 * @since 2.8.0
     967                 *
     968                 * @param int $user_id User ID.
     969                 */
     970                do_action( 'auth_redirect', $user_id );
    775971
    776972                // If the user wants ssl but the session is not ssl, redirect.
    777973                if ( !$secure && get_user_option('use_ssl', $user_id) && false !== strpos($_SERVER['REQUEST_URI'], 'wp-admin') ) {
    … …  
    8061002 * To avoid security exploits.
    8071003 *
    8081004 * @since 1.2.0
    809  * @uses do_action() Calls 'check_admin_referer' on $action.
    8101005 *
    8111006 * @param string $action Action nonce
    8121007 * @param string $query_arg where to look for nonce in $_REQUEST (since 2.5)
    … …  
    8221017                wp_nonce_ays($action);
    8231018                die();
    8241019        }
    825         do_action('check_admin_referer', $action, $result);
     1020
     1021        /**
     1022         * Fires once the admin request has been validated or not.
     1023         *
     1024         * @since 1.5.1
     1025         *
     1026         * @param string $action The nonce action.
     1027         * @param bool   $result Whether the admin request nonce was validated.
     1028         */
     1029        do_action( 'check_admin_referer', $action, $result );
    8261030        return $result;
    8271031}
    8281032endif;
    … …  
    8551059                        die( '-1' );
    8561060        }
    8571061
    858         do_action('check_ajax_referer', $action, $result);
     1062        /**
     1063         * Fires once the AJAX request has been validated or not.
     1064         *
     1065         * @since 2.1.0
     1066         *
     1067         * @param string $action The AJAX nonce action.
     1068         * @param bool   $result Whether the AJAX request nonce was validated.
     1069         */
     1070        do_action( 'check_ajax_referer', $action, $result );
    8591071
    8601072        return $result;
    8611073}
    … …  
    8661078 * Redirects to another page.
    8671079 *
    8681080 * @since 1.5.1
    869  * @uses apply_filters() Calls 'wp_redirect' hook on $location and $status.
    8701081 *
    8711082 * @param string $location The path to redirect to.
    8721083 * @param int $status Status code to use.
    … …  
    9681179 * If the host is not allowed, then the redirect is to $default supplied
    9691180 *
    9701181 * @since 2.8.1
    971  * @uses apply_filters() Calls 'allowed_redirect_hosts' on an array containing
    972  *              WordPress host string and $location host string.
    9731182 *
    9741183 * @param string $location The redirect to validate
    9751184 * @param string $default The value to return if $location is not allowed
    … …  
    10001209
    10011210        $wpp = parse_url(home_url());
    10021211
    1003         $allowed_hosts = (array) apply_filters('allowed_redirect_hosts', array($wpp['host']), isset($lp['host']) ? $lp['host'] : '');
     1212        /**
     1213         * Filter the whitelist of hosts to redirect to.
     1214         *
     1215         * @since 2.3.0
     1216         *
     1217         * @param array       $hosts An array of allowed hosts.
     1218         * @param bool|string $host  The parsed host; empty if not isset.
     1219         */
     1220        $allowed_hosts = (array) apply_filters( 'allowed_redirect_hosts', array($wpp['host']), isset($lp['host']) ? $lp['host'] : '' );
    10041221
    10051222        if ( isset($lp['host']) && ( !in_array($lp['host'], $allowed_hosts) && $lp['host'] != strtolower($wpp['host'])) )
    10061223                $location = $default;
    … …  
    10381255        }
    10391256
    10401257        /**
    1041          * Filter the list of emails to receive a comment notification.
     1258         * Filter the list of email addresses to receive a comment notification.
    10421259         *
    1043          * Normally just post authors are notified of emails.
    1044          * This filter lets you add others.
     1260         * By default, only post authors are notified of comments. This filter allows
     1261         * others to be added.
    10451262         *
    10461263         * @since 3.7.0
    10471264         *
    1048          * @param array $emails     Array of email addresses to receive a comment notification.
     1265         * @param array $emails     An array of email addresses to receive a comment notification.
    10491266         * @param int   $comment_id The comment ID.
    10501267         */
    10511268        $emails = apply_filters( 'comment_notification_recipients', $emails, $comment_id );
    … …  
    10621279        /**
    10631280         * Filter whether to notify comment authors of their comments on their own posts.
    10641281         *
    1065          * By default, comment authors don't get notified of their comments
    1066          * on their own post. This lets you override that.
     1282         * By default, comment authors aren't notified of their comments on their own
     1283         * posts. This filter allows you to override that.
    10671284         *
    10681285         * @since 3.8.0
    10691286         *
    1070          * @param bool $notify     Whether to notify the post author of their own comment. Default false.
     1287         * @param bool $notify     Whether to notify the post author of their own comment.
     1288         *                         Default false.
    10711289         * @param int  $comment_id The comment ID.
    10721290         */
    10731291        $notify_author = apply_filters( 'comment_notification_notify_author', false, $comment_id );
    … …  
    11631381        if ( isset($reply_to) )
    11641382                $message_headers .= $reply_to . "\n";
    11651383
    1166         $notify_message  = apply_filters( 'comment_notification_text',       $notify_message,  $comment_id );
    1167         $subject         = apply_filters( 'comment_notification_subject',    $subject,         $comment_id );
    1168         $message_headers = apply_filters( 'comment_notification_headers',    $message_headers, $comment_id );
     1384        /**
     1385         * Filter the comment notification email text.
     1386         *
     1387         * @since 1.5.2
     1388         *
     1389         * @param string $notify_message The comment notification email text.
     1390         * @param int    $comment_id     Comment ID.
     1391         */
     1392        $notify_message = apply_filters( 'comment_notification_text', $notify_message, $comment_id );
    11691393
     1394        /**
     1395         * Filter the comment notification email subject.
     1396         *
     1397         * @since 1.5.2
     1398         *
     1399         * @param string $subject    The comment notification email subject.
     1400         * @param int    $comment_id Comment ID.
     1401         */
     1402        $subject = apply_filters( 'comment_notification_subject', $subject, $comment_id );
     1403
     1404        /**
     1405         * Filter the comment notification email headers.
     1406         *
     1407         * @since 1.5.2
     1408         *
     1409         * @param string $message_headers Headers for the comment notification email.
     1410         * @param int    $comment_id      Comment ID.
     1411         */
     1412        $message_headers = apply_filters( 'comment_notification_headers', $message_headers, $comment_id );
     1413
    11701414        foreach ( $emails as $email ) {
    11711415                @wp_mail( $email, wp_specialchars_decode( $subject ), $notify_message, $message_headers );
    11721416        }
    … …  
    12491493        $subject = sprintf( __('[%1$s] Please moderate: "%2$s"'), $blogname, $post->post_title );
    12501494        $message_headers = '';
    12511495
    1252         $emails          = apply_filters( 'comment_moderation_recipients', $emails,          $comment_id );
    1253         $notify_message  = apply_filters( 'comment_moderation_text',       $notify_message,  $comment_id );
    1254         $subject         = apply_filters( 'comment_moderation_subject',    $subject,         $comment_id );
    1255         $message_headers = apply_filters( 'comment_moderation_headers',    $message_headers, $comment_id );
     1496        /**
     1497         * Filter the list of recipients for comment moderation emails.
     1498         *
     1499         * @since 3.7.0
     1500         *
     1501         * @param array $emails     List of email addresses to notify for comment moderation.
     1502         * @param int   $comment_id Comment ID.
     1503         */
     1504        $emails = apply_filters( 'comment_moderation_recipients', $emails, $comment_id );
    12561505
     1506        /**
     1507         * Filter the comment moderation email text.
     1508         *
     1509         * @since 1.5.2
     1510         *
     1511         * @param string $notify_message Text of the comment moderation email.
     1512         * @param int    $comment_id     Comment ID.
     1513         */
     1514        $notify_message = apply_filters( 'comment_moderation_text', $notify_message, $comment_id );
     1515
     1516        /**
     1517         * Filter the comment moderation email subject.
     1518         *
     1519         * @since 1.5.2
     1520         *
     1521         * @param string $subject    Subject of the comment moderation email.
     1522         * @param int    $comment_id Comment ID.
     1523         */
     1524        $subject = apply_filters( 'comment_moderation_subject', $subject, $comment_id );
     1525
     1526        /**
     1527         * Filter the comment moderation email headers.
     1528         *
     1529         * @since 2.8.0
     1530         *
     1531         * @param string $message_headers Headers for the comment moderation email.
     1532         * @param int    $comment_id      Comment ID.
     1533         */
     1534        $message_headers = apply_filters( 'comment_moderation_headers', $message_headers, $comment_id );
     1535
    12571536        foreach ( $emails as $email ) {
    12581537                @wp_mail( $email, wp_specialchars_decode( $subject ), $notify_message, $message_headers );
    12591538        }
    … …  
    13311610 * @return int
    13321611 */
    13331612function wp_nonce_tick() {
     1613        /**
     1614         * Filter the lifespan of nonces in seconds.
     1615         *
     1616         * @since 2.5.0
     1617         *
     1618         * @param int $lifespan Lifespan of nonces in seconds. Default 86,400 seconds, or one day.
     1619         */
    13341620        $nonce_life = apply_filters( 'nonce_life', DAY_IN_SECONDS );
    13351621
    13361622        return ceil(time() / ( $nonce_life / 2 ));
    … …  
    13531639function wp_verify_nonce($nonce, $action = -1) {
    13541640        $user = wp_get_current_user();
    13551641        $uid = (int) $user->ID;
    1356         if ( ! $uid )
     1642        if ( ! $uid ) {
     1643                /**
     1644                 * Filter whether the user who generated the nonce is logged out.
     1645                 *
     1646                 * @since 3.5.0
     1647                 *
     1648                 * @param int    $uid    ID of the nonce-owning user.
     1649                 * @param string $action The nonce action.
     1650                 */
    13571651                $uid = apply_filters( 'nonce_user_logged_out', $uid, $action );
     1652        }
    13581653
    13591654        $i = wp_nonce_tick();
    13601655
    … …  
    13811676function wp_create_nonce($action = -1) {
    13821677        $user = wp_get_current_user();
    13831678        $uid = (int) $user->ID;
    1384         if ( ! $uid )
     1679        if ( ! $uid ) {
     1680                /** This filter is documented in wp-includes/pluggable.php */
    13851681                $uid = apply_filters( 'nonce_user_logged_out', $uid, $action );
     1682        }
    13861683
    13871684        $i = wp_nonce_tick();
    13881685
    … …  
    14271724 */
    14281725function wp_salt( $scheme = 'auth' ) {
    14291726        static $cached_salts = array();
    1430         if ( isset( $cached_salts[ $scheme ] ) )
     1727        if ( isset( $cached_salts[ $scheme ] ) ) {
     1728                /**
     1729                 * Filter the WordPress salt.
     1730                 *
     1731                 * @since 2.5.0
     1732                 *
     1733                 * @param string $cached_salt Cached salt for the given scheme.
     1734                 * @param string $scheme      Authentication scheme. Values include 'auth',
     1735                 *                            'secure_auth', 'logged_in', and 'nonce'.
     1736                 */
    14311737                return apply_filters( 'salt', $cached_salts[ $scheme ], $scheme );
     1738        }
    14321739
    14331740        static $duplicated_keys;
    14341741        if ( null === $duplicated_keys ) {
    … …  
    14741781        }
    14751782
    14761783        $cached_salts[ $scheme ] = $key . $salt;
     1784
     1785        /** This filter is documented in wp-includes/pluggable.php */
    14771786        return apply_filters( 'salt', $cached_salts[ $scheme ], $scheme );
    14781787}
    14791788endif;
    … …  
    15571866                        $hash = wp_hash_password($password);
    15581867                }
    15591868
    1560                 return apply_filters('check_password', $check, $password, $hash, $user_id);
     1869                /**
     1870                 * Filter whether the plaintext password matches the encrypted password.
     1871                 *
     1872                 * @since 2.5.0
     1873                 *
     1874                 * @param bool   $check   Whether the passwords match.
     1875                 * @param string $hash    The hashed password.
     1876                 * @param int    $user_id User ID.
     1877                 */
     1878                return apply_filters( 'check_password', $check, $password, $hash, $user_id );
    15611879        }
    15621880
    15631881        // If the stored hash is longer than an MD5, presume the
    … …  
    15701888
    15711889        $check = $wp_hasher->CheckPassword($password, $hash);
    15721890
    1573         return apply_filters('check_password', $check, $password, $hash, $user_id);
     1891        /** This filter is documented in wp-includes/pluggable.php */
     1892        return apply_filters( 'check_password', $check, $password, $hash, $user_id );
    15741893}
    15751894endif;
    15761895
    … …  
    15981917                $password .= substr($chars, wp_rand(0, strlen($chars) - 1), 1);
    15991918        }
    16001919
    1601         // random_password filter was previously in random_password function which was deprecated
    1602         return apply_filters('random_password', $password);
     1920        /**
     1921         * Filter the randomly-generated password.
     1922         *
     1923         * @since 3.0.0
     1924         *
     1925         * @param string $password The generated password.
     1926         */
     1927        return apply_filters( 'random_password', $password );
    16031928}
    16041929endif;
    16051930
    … …  
    17072032                        $email = $user->user_email;
    17082033        } elseif ( is_object($id_or_email) ) {
    17092034                // No avatar for pingbacks or trackbacks
     2035
     2036                /**
     2037                 * Filter the list of allowed comment types for retrieving avatars.
     2038                 *
     2039                 * @since 3.0.0
     2040                 *
     2041                 * @param array $types An array of content types. Default only contains 'comment'.
     2042                 */
    17102043                $allowed_comment_types = apply_filters( 'get_avatar_comment_types', array( 'comment' ) );
    17112044                if ( ! empty( $id_or_email->comment_type ) && ! in_array( $id_or_email->comment_type, (array) $allowed_comment_types ) )
    17122045                        return false;
    … …  
    17732106                $avatar = "<img alt='{$safe_alt}' src='{$default}' class='avatar avatar-{$size} photo avatar-default' height='{$size}' width='{$size}' />";
    17742107        }
    17752108
    1776         return apply_filters('get_avatar', $avatar, $id_or_email, $size, $default, $alt);
     2109        /**
     2110         * Filter the avatar to retrieve.
     2111         *
     2112         * @since 2.5.0
     2113         *
     2114         * @param string            $avatar      Image tag for the user's avatar.
     2115         * @param int|object|string $id_or_email A user ID, email address, or comment object.
     2116         * @param int               $size        Square avatar width and height in pixels to retrieve.
     2117         * @param string            $alt         Alternative text to use in the avatar image tag.
     2118         *                                       Default empty.
     2119         */
     2120        return apply_filters( 'get_avatar', $avatar, $id_or_email, $size, $default, $alt );
    17772121}
    17782122endif;
    17792123