WordPress.org
Get WordPress

Make WordPress Core

Ticket #26888: 26888.2.diff

File 26888.2.diff, 26.5 KB (added by kpdesign, 11 years ago)

Second 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 length of the authentication cookie expiration period.
     774                 *
     775                 * @since 2.8.0
     776                 *
     777                 * @param int  $length   Length 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 to use a secure authentication cookie.
     799         *
     800         * @since 3.1.0
     801         *
     802         * @param bool $secure  Whether to use a secure auth cookie. Default is value
     803         *                      of is_ssl(), or false.
     804         * @param int  $user_id User ID.
     805         */
     806        $secure = apply_filters( 'secure_auth_cookie', $secure, $user_id );
    673807
     808        /**
     809         * Filter the secure logged-in cookie.
     810         *
     811         * @since 3.1.0
     812         *
     813         * @param bool|string $cookie  The secure logged-in cookie. Default false.
     814         * @param int         $user_id User ID.
     815         * @param bool        $secure  Whether to use a secure auth cookie. Default is
     816         *                             value of is_ssl(), or false.
     817         */
     818        $secure_logged_in_cookie = apply_filters( 'secure_logged_in_cookie', false, $user_id, $secure );
     819
    674820        if ( $secure ) {
    675821                $auth_cookie_name = SECURE_AUTH_COOKIE;
    676822                $scheme = 'secure_auth';
    … …  
    682828        $auth_cookie = wp_generate_auth_cookie($user_id, $expiration, $scheme);
    683829        $logged_in_cookie = wp_generate_auth_cookie($user_id, $expiration, 'logged_in');
    684830
    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');
     831        /**
     832         * Fires immediately before the authentication cookie is set.
     833         *
     834         * @since 2.5.0
     835         *
     836         * @param string $auth_cookie Authentication cookie.
     837         * @param int    $expire      Login grace period in seconds. Default 43,200 seconds, or 12 hours.
     838         * @param int    $expiration  Duration in seconds the authentication cookie should be valid.
     839         *                            Default 1,209,600 seconds, or 14 days.
     840         * @param int    $user_id     User ID.
     841         * @param string $scheme      Authentication scheme. Values include 'auth', 'secure_auth', or 'logged_in'.
     842         */
     843        do_action( 'set_auth_cookie', $auth_cookie, $expire, $expiration, $user_id, $scheme );
    687844
     845        /**
     846         * Fires immediately before the secure authentication cookie is set.
     847         *
     848         * @since 2.6.0
     849         *
     850         * @param string $logged_in_cookie The logged-in cookie.
     851         * @param int    $expire           Login grace period in seconds. Default 43,200 seconds, or 12 hours.
     852         * @param int    $expiration       Duration in seconds the authentication cookie should be valid.
     853         *                                 Default 1,209,600 seconds, or 14 days.
     854         * @param int    $user_id          User ID.
     855         * @param string $scheme           Authentication scheme. Default 'logged_in'.
     856         */
     857        do_action( 'set_logged_in_cookie', $logged_in_cookie, $expire, $expiration, $user_id, 'logged_in' );
     858
    688859        setcookie($auth_cookie_name, $auth_cookie, $expire, PLUGINS_COOKIE_PATH, COOKIE_DOMAIN, $secure, true);
    689860        setcookie($auth_cookie_name, $auth_cookie, $expire, ADMIN_COOKIE_PATH, COOKIE_DOMAIN, $secure, true);
    690861        setcookie(LOGGED_IN_COOKIE, $logged_in_cookie, $expire, COOKIEPATH, COOKIE_DOMAIN, $secure_logged_in_cookie, true);
    … …  
    700871 * @since 2.5.0
    701872 */
    702873function wp_clear_auth_cookie() {
    703         do_action('clear_auth_cookie');
     874        /**
     875         * Fires just before the authentication cookie is cleared.
     876         *
     877         * @since 2.7.0
     878         */
     879        do_action( 'clear_auth_cookie' );
    704880
    705881        setcookie( AUTH_COOKIE,        ' ', time() - YEAR_IN_SECONDS, ADMIN_COOKIE_PATH,   COOKIE_DOMAIN );
    706882        setcookie( SECURE_AUTH_COOKIE, ' ', time() - YEAR_IN_SECONDS, ADMIN_COOKIE_PATH,   COOKIE_DOMAIN );
    … …  
    752928
    753929        $secure = ( is_ssl() || force_ssl_admin() );
    754930
    755         $secure = apply_filters('secure_auth_redirect', $secure);
     931        /**
     932         * Filter whether to use a secure authentication redirect.
     933         *
     934         * @since 3.1.0
     935         *
     936         * @param bool $secure Whether to use a secure authentication redirect. Default false.
     937         */
     938        $secure = apply_filters( 'secure_auth_redirect', $secure );
    756939
    757940        // If https is required and request is http, redirect
    758941        if ( $secure && !is_ssl() && false !== strpos($_SERVER['REQUEST_URI'], 'wp-admin') ) {
    … …  
    765948                }
    766949        }
    767950
    768         if ( is_user_admin() )
     951        if ( is_user_admin() ) {
    769952                $scheme = 'logged_in';
    770         else
     953        } else {
     954                /**
     955                 * Filter the authentication redirect scheme.
     956                 *
     957                 * @since 2.9.0
     958                 *
     959                 * @param string $scheme Authentication redirect scheme. Default empty.
     960                 */
    771961                $scheme = apply_filters( 'auth_redirect_scheme', '' );
     962        }
    772963
    773964        if ( $user_id = wp_validate_auth_cookie( '',  $scheme) ) {
    774                 do_action('auth_redirect', $user_id);
     965                /**
     966                 * Fires before the authentication redirect.
     967                 *
     968                 * @since 2.8.0
     969                 *
     970                 * @param int $user_id User ID.
     971                 */
     972                do_action( 'auth_redirect', $user_id );
    775973
    776974                // If the user wants ssl but the session is not ssl, redirect.
    777975                if ( !$secure && get_user_option('use_ssl', $user_id) && false !== strpos($_SERVER['REQUEST_URI'], 'wp-admin') ) {
    … …  
    8061004 * To avoid security exploits.
    8071005 *
    8081006 * @since 1.2.0
    809  * @uses do_action() Calls 'check_admin_referer' on $action.
    8101007 *
    8111008 * @param string $action Action nonce
    8121009 * @param string $query_arg where to look for nonce in $_REQUEST (since 2.5)
    … …  
    8221019                wp_nonce_ays($action);
    8231020                die();
    8241021        }
    825         do_action('check_admin_referer', $action, $result);
     1022
     1023        /**
     1024         * Fires once the admin request has been validated or not.
     1025         *
     1026         * @since 1.5.1
     1027         *
     1028         * @param string $action The nonce action.
     1029         * @param bool   $result Whether the admin request nonce was validated.
     1030         */
     1031        do_action( 'check_admin_referer', $action, $result );
    8261032        return $result;
    8271033}
    8281034endif;
    … …  
    8551061                        die( '-1' );
    8561062        }
    8571063
    858         do_action('check_ajax_referer', $action, $result);
     1064        /**
     1065         * Fires once the AJAX request has been validated or not.
     1066         *
     1067         * @since 2.1.0
     1068         *
     1069         * @param string $action The AJAX nonce action.
     1070         * @param bool   $result Whether the AJAX request nonce was validated.
     1071         */
     1072        do_action( 'check_ajax_referer', $action, $result );
    8591073
    8601074        return $result;
    8611075}
    … …  
    8661080 * Redirects to another page.
    8671081 *
    8681082 * @since 1.5.1
    869  * @uses apply_filters() Calls 'wp_redirect' hook on $location and $status.
    8701083 *
    8711084 * @param string $location The path to redirect to.
    8721085 * @param int $status Status code to use.
    … …  
    9681181 * If the host is not allowed, then the redirect is to $default supplied
    9691182 *
    9701183 * @since 2.8.1
    971  * @uses apply_filters() Calls 'allowed_redirect_hosts' on an array containing
    972  *              WordPress host string and $location host string.
    9731184 *
    9741185 * @param string $location The redirect to validate
    9751186 * @param string $default The value to return if $location is not allowed
    … …  
    10001211
    10011212        $wpp = parse_url(home_url());
    10021213
    1003         $allowed_hosts = (array) apply_filters('allowed_redirect_hosts', array($wpp['host']), isset($lp['host']) ? $lp['host'] : '');
     1214        /**
     1215         * Filter the list of hosts allowed to be redirected to.
     1216         *
     1217         * @since 2.3.0
     1218         *
     1219         * @param array       $hosts An array of allowed hosts.
     1220         * @param bool|string $host  The parsed host; empty if not isset.
     1221         */
     1222        $allowed_hosts = (array) apply_filters( 'allowed_redirect_hosts', array($wpp['host']), isset($lp['host']) ? $lp['host'] : '' );
    10041223
    10051224        if ( isset($lp['host']) && ( !in_array($lp['host'], $allowed_hosts) && $lp['host'] != strtolower($wpp['host'])) )
    10061225                $location = $default;
    … …  
    10381257        }
    10391258
    10401259        /**
    1041          * Filter the list of emails to receive a comment notification.
     1260         * Filter the list of email addresses to receive a comment notification.
    10421261         *
    1043          * Normally just post authors are notified of emails.
    1044          * This filter lets you add others.
     1262         * By default, only post authors are notified of comments. This filter allows
     1263         * others to be added.
    10451264         *
    10461265         * @since 3.7.0
    10471266         *
    1048          * @param array $emails     Array of email addresses to receive a comment notification.
     1267         * @param array $emails     An array of email addresses to receive a comment notification.
    10491268         * @param int   $comment_id The comment ID.
    10501269         */
    10511270        $emails = apply_filters( 'comment_notification_recipients', $emails, $comment_id );
    … …  
    10621281        /**
    10631282         * Filter whether to notify comment authors of their comments on their own posts.
    10641283         *
    1065          * By default, comment authors don't get notified of their comments
    1066          * on their own post. This lets you override that.
     1284         * By default, comment authors aren't notified of their comments on their own
     1285         * posts. This filter allows you to override that.
    10671286         *
    10681287         * @since 3.8.0
    10691288         *
    1070          * @param bool $notify     Whether to notify the post author of their own comment. Default false.
     1289         * @param bool $notify     Whether to notify the post author of their own comment.
     1290         *                         Default false.
    10711291         * @param int  $comment_id The comment ID.
    10721292         */
    10731293        $notify_author = apply_filters( 'comment_notification_notify_author', false, $comment_id );
    … …  
    11631383        if ( isset($reply_to) )
    11641384                $message_headers .= $reply_to . "\n";
    11651385
    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 );
     1386        /**
     1387         * Filter the comment notification email text.
     1388         *
     1389         * @since 1.5.2
     1390         *
     1391         * @param string $notify_message The comment notification email text.
     1392         * @param int    $comment_id     Comment ID.
     1393         */
     1394        $notify_message = apply_filters( 'comment_notification_text', $notify_message, $comment_id );
    11691395
     1396        /**
     1397         * Filter the comment notification email subject.
     1398         *
     1399         * @since 1.5.2
     1400         *
     1401         * @param string $subject    The comment notification email subject.
     1402         * @param int    $comment_id Comment ID.
     1403         */
     1404        $subject = apply_filters( 'comment_notification_subject', $subject, $comment_id );
     1405
     1406        /**
     1407         * Filter the comment notification email headers.
     1408         *
     1409         * @since 1.5.2
     1410         *
     1411         * @param string $message_headers Headers for the comment notification email.
     1412         * @param int    $comment_id      Comment ID.
     1413         */
     1414        $message_headers = apply_filters( 'comment_notification_headers', $message_headers, $comment_id );
     1415
    11701416        foreach ( $emails as $email ) {
    11711417                @wp_mail( $email, $subject, $notify_message, $message_headers );
    11721418        }
    … …  
    12491495        $subject = sprintf( __('[%1$s] Please moderate: "%2$s"'), $blogname, $post->post_title );
    12501496        $message_headers = '';
    12511497
    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 );
     1498        /**
     1499         * Filter the list of recipients for comment moderation emails.
     1500         *
     1501         * @since 3.7.0
     1502         *
     1503         * @param array $emails     List of email addresses to notify for comment moderation.
     1504         * @param int   $comment_id Comment ID.
     1505         */
     1506        $emails = apply_filters( 'comment_moderation_recipients', $emails, $comment_id );
    12561507
     1508        /**
     1509         * Filter the comment moderation email text.
     1510         *
     1511         * @since 1.5.2
     1512         *
     1513         * @param string $notify_message Text of the comment moderation email.
     1514         * @param int    $comment_id     Comment ID.
     1515         */
     1516        $notify_message = apply_filters( 'comment_moderation_text', $notify_message, $comment_id );
     1517
     1518        /**
     1519         * Filter the comment moderation email subject.
     1520         *
     1521         * @since 1.5.2
     1522         *
     1523         * @param string $subject    Subject of the comment moderation email.
     1524         * @param int    $comment_id Comment ID.
     1525         */
     1526        $subject = apply_filters( 'comment_moderation_subject', $subject, $comment_id );
     1527
     1528        /**
     1529         * Filter the comment moderation email headers.
     1530         *
     1531         * @since 2.8.0
     1532         *
     1533         * @param string $message_headers Headers for the comment moderation email.
     1534         * @param int    $comment_id      Comment ID.
     1535         */
     1536        $message_headers = apply_filters( 'comment_moderation_headers', $message_headers, $comment_id );
     1537
    12571538        foreach ( $emails as $email ) {
    12581539                @wp_mail( $email, $subject, $notify_message, $message_headers );
    12591540        }
    … …  
    13311612 * @return int
    13321613 */
    13331614function wp_nonce_tick() {
     1615        /**
     1616         * Filter the lifespan of nonces in seconds.
     1617         *
     1618         * @since 2.5.0
     1619         *
     1620         * @param int $lifespan Lifespan of nonces in seconds. Default 86,400 seconds, or one day.
     1621         */
    13341622        $nonce_life = apply_filters( 'nonce_life', DAY_IN_SECONDS );
    13351623
    13361624        return ceil(time() / ( $nonce_life / 2 ));
    … …  
    13531641function wp_verify_nonce($nonce, $action = -1) {
    13541642        $user = wp_get_current_user();
    13551643        $uid = (int) $user->ID;
    1356         if ( ! $uid )
     1644        if ( ! $uid ) {
     1645                /**
     1646                 * Filter whether the user who generated the nonce is logged out.
     1647                 *
     1648                 * @since 3.5.0
     1649                 *
     1650                 * @param int    $uid    ID of the nonce-owning user.
     1651                 * @param string $action The nonce action.
     1652                 */
    13571653                $uid = apply_filters( 'nonce_user_logged_out', $uid, $action );
     1654        }
    13581655
    13591656        $i = wp_nonce_tick();
    13601657
    … …  
    13811678function wp_create_nonce($action = -1) {
    13821679        $user = wp_get_current_user();
    13831680        $uid = (int) $user->ID;
    1384         if ( ! $uid )
     1681        if ( ! $uid ) {
     1682                /** This filter is documented in wp-includes/pluggable.php */
    13851683                $uid = apply_filters( 'nonce_user_logged_out', $uid, $action );
     1684        }
    13861685
    13871686        $i = wp_nonce_tick();
    13881687
    … …  
    14271726 */
    14281727function wp_salt( $scheme = 'auth' ) {
    14291728        static $cached_salts = array();
    1430         if ( isset( $cached_salts[ $scheme ] ) )
     1729        if ( isset( $cached_salts[ $scheme ] ) ) {
     1730                /**
     1731                 * Filter the WordPress salt.
     1732                 *
     1733                 * @since 2.5.0
     1734                 *
     1735                 * @param string $cached_salt Cached salt for the given scheme.
     1736                 * @param string $scheme      Authentication scheme. Values include 'auth',
     1737                 *                            'secure_auth', 'logged_in', and 'nonce'.
     1738                 */
    14311739                return apply_filters( 'salt', $cached_salts[ $scheme ], $scheme );
     1740        }
    14321741
    14331742        static $duplicated_keys;
    14341743        if ( null === $duplicated_keys ) {
    … …  
    14741783        }
    14751784
    14761785        $cached_salts[ $scheme ] = $key . $salt;
     1786
     1787        /** This filter is documented in wp-includes/pluggable.php */
    14771788        return apply_filters( 'salt', $cached_salts[ $scheme ], $scheme );
    14781789}
    14791790endif;
    … …  
    15571868                        $hash = wp_hash_password($password);
    15581869                }
    15591870
    1560                 return apply_filters('check_password', $check, $password, $hash, $user_id);
     1871                /**
     1872                 * Filter whether the plaintext password matches the encrypted password.
     1873                 *
     1874                 * @since 2.5.0
     1875                 *
     1876                 * @param bool   $check   Whether the passwords match.
     1877                 * @param string $hash    The hashed password.
     1878                 * @param int    $user_id User ID.
     1879                 */
     1880                return apply_filters( 'check_password', $check, $password, $hash, $user_id );
    15611881        }
    15621882
    15631883        // If the stored hash is longer than an MD5, presume the
    … …  
    15701890
    15711891        $check = $wp_hasher->CheckPassword($password, $hash);
    15721892
    1573         return apply_filters('check_password', $check, $password, $hash, $user_id);
     1893        /** This filter is documented in wp-includes/pluggable.php */
     1894        return apply_filters( 'check_password', $check, $password, $hash, $user_id );
    15741895}
    15751896endif;
    15761897
    … …  
    15981919                $password .= substr($chars, wp_rand(0, strlen($chars) - 1), 1);
    15991920        }
    16001921
    1601         // random_password filter was previously in random_password function which was deprecated
    1602         return apply_filters('random_password', $password);
     1922        /**
     1923         * Filter the randomly-generated password.
     1924         *
     1925         * @since 3.0.0
     1926         *
     1927         * @param string $password The generated password.
     1928         */
     1929        return apply_filters( 'random_password', $password );
    16031930}
    16041931endif;
    16051932
    … …  
    17072034                        $email = $user->user_email;
    17082035        } elseif ( is_object($id_or_email) ) {
    17092036                // No avatar for pingbacks or trackbacks
     2037
     2038                /**
     2039                 * Filter the list of allowed comment types for retrieving avatars.
     2040                 *
     2041                 * @since 3.0.0
     2042                 *
     2043                 * @param array $types An array of content types. Default only contains 'comment'.
     2044                 */
    17102045                $allowed_comment_types = apply_filters( 'get_avatar_comment_types', array( 'comment' ) );
    17112046                if ( ! empty( $id_or_email->comment_type ) && ! in_array( $id_or_email->comment_type, (array) $allowed_comment_types ) )
    17122047                        return false;
    … …  
    17732108                $avatar = "<img alt='{$safe_alt}' src='{$default}' class='avatar avatar-{$size} photo avatar-default' height='{$size}' width='{$size}' />";
    17742109        }
    17752110
    1776         return apply_filters('get_avatar', $avatar, $id_or_email, $size, $default, $alt);
     2111        /**
     2112         * Filter the avatar to retrieve.
     2113         *
     2114         * @since 2.5.0
     2115         *
     2116         * @param string            $avatar      Image tag for the user's avatar.
     2117         * @param int|object|string $id_or_email A user ID, email address, or comment object.
     2118         * @param int               $size        Square avatar width and height in pixels to retrieve.
     2119         * @param string            $alt         Alternative text to use in the avatar image tag.
     2120         *                                       Default empty.
     2121         */
     2122        return apply_filters( 'get_avatar', $avatar, $id_or_email, $size, $default, $alt );
    17772123}
    17782124endif;
    17792125