WordPress.org
Get WordPress

Make WordPress Core

Changeset 25701


Ignore:
Timestamp:
10/06/2013 04:23:39 PM (11 years ago)
Author:
DrewAPicture
Message:

Inline documentation for hooks in wp-login.php.

Props ShinichiN, kpdesign.
Fixes #25393.

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/src/wp-login.php

    r25696 r25701  
    2424
    2525/**
    26  * Outputs the header for the login page.
     26 * Output the login page header.
    2727 *
    28  * @uses do_action() Calls the 'login_head' for outputting HTML in the Log In
    29  *      header.
    30  * @uses apply_filters() Calls 'login_headerurl' for the top login link.
    31  * @uses apply_filters() Calls 'login_headertitle' for the top login title.
    32  * @uses apply_filters() Calls 'login_message' on the message to display in the
    33  *      header.
    34  * @uses $error The error global, which is checked for displaying errors.
    35  *
    36  * @param string $title Optional. WordPress Log In Page title to display in
    37  *      <title/> element.
    38  * @param string $message Optional. Message to display in header.
     28 * @param string $title    Optional. WordPress Log In Page title to display in <title/> element. Default 'Log In'.
     29 * @param string $message  Optional. Message to display in header. Default empty.
     30 * @param string $wp_error Optional. The error to pass. Default empty.
    3931 * @param WP_Error $wp_error Optional. WordPress Error Object
    4032 */
    … …  
    5345    // Shake it!
    5446    $shake_error_codes = array( 'empty_password', 'empty_email', 'invalid_email', 'invalidcombo', 'empty_username', 'invalid_username', 'incorrect_password' );
     47    /**
     48     * Filter the error codes array for shaking the login form.
     49     *
     50     * @since 3.0.0
     51     *
     52     * @param array $shake_error_codes Error codes that shake the login form.
     53     */
    5554    $shake_error_codes = apply_filters( 'shake_error_codes', $shake_error_codes );
    5655
    … …  
    7776    }
    7877
     78    /**
     79     * Enqueue scripts and styles for the login page.
     80     *
     81     * @since 3.1.0
     82     */
    7983    do_action( 'login_enqueue_scripts' );
     84    /**
     85     * Fires in the login page header after scripts are enqueued.
     86     *
     87     * @since 2.1.0
     88     */
    8089    do_action( 'login_head' );
    8190
    … …  
    8897    }
    8998
    90     $login_header_url   = apply_filters( 'login_headerurl',   $login_header_url   );
     99    /**
     100     * Filter link URL of the header logo above login form.
     101     *
     102     * @since 2.1.0
     103     *
     104     * @param string $login_header_url Login header logo URL.
     105     */
     106    $login_header_url = apply_filters( 'login_headerurl', $login_header_url );
     107    /**
     108     * Filter the title attribute of the header logo above login form.
     109     *
     110     * @since 2.1.0
     111     *
     112     * @param string $login_header_title Login header logo title attribute.
     113     */
    91114    $login_header_title = apply_filters( 'login_headertitle', $login_header_title );
    92115
    … …  
    106129    }
    107130
     131    /**
     132     * Filter the login page body classes.
     133     *
     134     * @since 3.5.0
     135     *
     136     * @param array  $classes An array of body classes.
     137     * @param string $action  The action that brought the visitor to the login page.
     138     */
    108139    $classes = apply_filters( 'login_body_class', $classes, $action );
    109140
    … …  
    117148    unset( $login_header_url, $login_header_title );
    118149
    119     $message = apply_filters('login_message', $message);
     150    /**
     151     * Filter the message to display above the login form.
     152     *
     153     * @since 2.1.0
     154     *
     155     * @param string $message Login message text.
     156     */
     157    $message = apply_filters( 'login_message', $message );
    120158    if ( !empty( $message ) )
    121159        echo $message . "\n";
    … …  
    139177            }
    140178        }
    141         if ( !empty($errors) )
    142             echo '<div id="login_error">' . apply_filters('login_errors', $errors) . "</div>\n";
    143         if ( !empty($messages) )
    144             echo '<p class="message">' . apply_filters('login_messages', $messages) . "</p>\n";
     179        if ( ! empty( $errors ) ) {
     180            /**
     181             * Filter the error messages displayed above the login form.
     182             *
     183             * @since 2.1.0
     184             *
     185             * @param string $errors Login error message.
     186             */
     187            echo '<div id="login_error">' . apply_filters( 'login_errors', $errors ) . "</div>\n";
     188        }
     189        if ( ! empty( $messages ) ) {
     190            /**
     191             * Filter instructional messages displayed above the login form.
     192             *
     193             * @since 2.5.0
     194             *
     195             * @param string $messages Login messages.
     196             */
     197            echo '<p class="message">' . apply_filters( 'login_messages', $messages ) . "</p>\n";
     198        }
    145199    }
    146200} // End of login_header()
    … …  
    168222    <?php endif; ?>
    169223
    170     <?php do_action('login_footer'); ?>
     224    <?php
     225    /**
     226     * Fires in the login page footer.
     227     *
     228     * @since 3.1.0
     229     */
     230    do_action( 'login_footer' ); ?>
    171231    <div class="clear"></div>
    172232    </body>
    … …  
    218278    }
    219279
    220     do_action('lostpassword_post');
     280    /**
     281     * Fires before errors are returned from a password reset request.
     282     *
     283     * @since 2.1.0
     284     */
     285    do_action( 'lostpassword_post' );
    221286
    222287    if ( $errors->get_error_code() )
    … …  
    232297    $user_email = $user_data->user_email;
    233298
    234     do_action('retreive_password', $user_login);  // Misspelled and deprecated
    235     do_action('retrieve_password', $user_login);
    236 
    237     $allow = apply_filters('allow_password_reset', true, $user_data->ID);
     299    /**
     300     * Fires before a new password is retrieved.
     301     *
     302     * @since 1.5.2
     303     * @deprecated 1.5.2 Misspelled. Use 'retrieve_password' hook instead.
     304     *
     305     * @param string $user_login The user login name.
     306     */
     307    do_action( 'retreive_password', $user_login );
     308    /**
     309     * Fires before a new password is retrieved.
     310     *
     311     * @since 1.5.2
     312     *
     313     * @param string $user_login The user login name.
     314     */
     315    do_action( 'retrieve_password', $user_login );
     316
     317    /**
     318     * Filter whether to allow a password to be reset.
     319     *
     320     * @since 2.7.0
     321     *
     322     * @param bool true           Whether to allow the password to be reset. Default true.
     323     * @param int  $user_data->ID The ID of the user attempting to reset a password.
     324     */
     325    $allow = apply_filters( 'allow_password_reset', true, $user_data->ID );
    238326
    239327    if ( ! $allow )
    … …  
    279367    $title = sprintf( __('[%s] Password Reset'), $blogname );
    280368
    281     $title = apply_filters('retrieve_password_title', $title);
    282     $message = apply_filters('retrieve_password_message', $message, $key);
     369    /**
     370     * Filter the subject of the password reset email.
     371     *
     372     * @since 2.8.0
     373     *
     374     * @param string $title Default email title.
     375     */
     376    $title = apply_filters( 'retrieve_password_title', $title );
     377    /**
     378     * Filter the message body of the password reset mail.
     379     *
     380     * @since 2.8.0
     381     *
     382     * @param string $message Default mail message.
     383     * @param string $key     The activation key.
     384     */
     385    $message = apply_filters( 'retrieve_password_message', $message, $key );
    283386
    284387    if ( $message && !wp_mail($user_email, $title, $message) )
    … …  
    320423    setcookie(TEST_COOKIE, 'WP Cookie check', 0, SITECOOKIEPATH, COOKIE_DOMAIN);
    321424
    322 // allow plugins to override the default actions, and to add extra actions if they want
     425/**
     426 * Fires when the login form is initialized.
     427 *
     428 * @since 3.2.0
     429 */
    323430do_action( 'login_init' );
     431/**
     432 * Fires before a specified login form action.
     433 *
     434 * The dynamic portion of the hook name, $action, refers to the action
     435 * that brought the visitor to the login form. Actions include 'postpass',
     436 * 'logout', 'lostpassword', etc.
     437 *
     438 * @since 2.8.0
     439 */
    324440do_action( 'login_form_' . $action );
    325441
    … …  
    334450
    335451    /**
    336      * Filter the life of the post password cookie.
    337      *
    338      * By default, the cookie expires 10 days from now.
    339      * To turn this into a session cookie, return 0.
     452     * Filter the life span of the post password cookie.
     453     *
     454     * By default, the cookie expires 10 days from creation. To turn this
     455     * into a session cookie, return 0.
    340456     *
    341457     * @since 3.7.0
     458     *
    342459     * @param int $expires The expiry time, as passed to setcookie().
    343460     */
    … …  
    379496    }
    380497
    381     $redirect_to = apply_filters( 'lostpassword_redirect', !empty( $_REQUEST['redirect_to'] ) ? $_REQUEST['redirect_to'] : '' );
    382 
    383     do_action('lost_password');
     498    $lostpassword_redirect = ! empty( $_REQUEST['redirect_to'] ) ? $_REQUEST['redirect_to'] : '';
     499    /**
     500     * Filter the URL redirected to after submitting the lostpassword/retrievepassword form.
     501     *
     502     * @since 3.0.0
     503     *
     504     * @param string $lostpassword_redirect The redirect destination URL.
     505     */
     506    $redirect_to = apply_filters( 'lostpassword_redirect', $lostpassword_redirect );
     507
     508    /**
     509     * Fires before the lost password form.
     510     *
     511     * @since 1.5.2
     512     */
     513    do_action( 'lost_password' );
     514
    384515    login_header(__('Lost Password'), '<p class="message">' . __('Please enter your username or email address. You will receive a link to create a new password via email.') . '</p>', $errors);
    385516
    … …  
    393524        <input type="text" name="user_login" id="user_login" class="input" value="<?php echo esc_attr($user_login); ?>" size="20" /></label>
    394525    </p>
    395 <?php do_action('lostpassword_form'); ?>
     526    <?php
     527    /**
     528     * Fires inside the lostpassword <form> tags, before the hidden fields.
     529     *
     530     * @since 2.1.0
     531     */
     532    do_action( 'lostpassword_form' ); ?>
    396533    <input type="hidden" name="redirect_to" value="<?php echo esc_attr( $redirect_to ); ?>" />
    397534    <p class="submit"><input type="submit" name="wp-submit" id="wp-submit" class="button button-primary button-large" value="<?php esc_attr_e('Get New Password'); ?>" /></p>
    … …  
    400537<p id="nav">
    401538<a href="<?php echo esc_url( wp_login_url() ); ?>"><?php _e('Log in') ?></a>
    402 <?php if ( get_option( 'users_can_register' ) ) : ?>
    403  | <?php echo apply_filters( 'register', sprintf( '<a href="%s">%s</a>', esc_url( wp_registration_url() ), __( 'Register' ) ) ); ?>
    404 <?php endif; ?>
     539<?php
     540if ( get_option( 'users_can_register' ) ) :
     541    $registration_url = sprintf( '<a href="%s">%s</a>', esc_url( wp_registration_url() ), __( 'Register' ) );
     542    /**
     543     * Filter the registration URL below the login form.
     544     *
     545     * @since 1.5.2
     546     *
     547     * @param string $registration_url Registration URL.
     548     */
     549    echo ' | ' . apply_filters( 'register', $registration_url );
     550endif;
     551?>
    405552</p>
    406553
    … …  
    426573        $errors->add( 'password_reset_mismatch', __( 'The passwords do not match.' ) );
    427574
     575    /**
     576     * Fires before the password reset procedure is validated.
     577     *
     578     * @since 3.5.0
     579     *
     580     * @param object           $errors WP Error object.
     581     * @param WP_User|WP_Error $user   WP_User object if the login and reset key match. WP_Error object otherwise.
     582     */
    428583    do_action( 'validate_password_reset', $errors, $user );
    429584
    … …  
    462617<p id="nav">
    463618<a href="<?php echo esc_url( wp_login_url() ); ?>"><?php _e( 'Log in' ); ?></a>
    464 <?php if ( get_option( 'users_can_register' ) ) : ?>
    465  | <?php echo apply_filters( 'register', sprintf( '<a href="%s">%s</a>', esc_url( wp_registration_url() ), __( 'Register' ) ) ); ?>
    466 <?php endif; ?>
     619<?php
     620if ( get_option( 'users_can_register' ) ) :
     621    $registration_url = sprintf( '<a href="%s">%s</a>', esc_url( wp_registration_url() ), __( 'Register' ) );
     622    //duplicate_hook
     623    echo ' | ' . apply_filters( 'register', $registration_url );
     624endif;
     625?>
    467626</p>
    468627
    … …  
    473632case 'register' :
    474633    if ( is_multisite() ) {
    475         // Multisite uses wp-signup.php
    476         wp_redirect( apply_filters( 'wp_signup_location', network_site_url('wp-signup.php') ) );
     634        $sign_up_url = network_site_url( 'wp-signup.php' );
     635        /**
     636         * Filter the Multisite sign up URL.
     637         *
     638         * @since 3.0.0
     639         *
     640         * @param string $sign_up_url The sign up URL.
     641         */
     642        wp_redirect( apply_filters( 'wp_signup_location', $sign_up_url ) );
    477643        exit;
    478644    }
    … …  
    496662    }
    497663
    498     $redirect_to = apply_filters( 'registration_redirect', !empty( $_REQUEST['redirect_to'] ) ? $_REQUEST['redirect_to'] : '' );
     664    $registration_redirect = ! empty( $_REQUEST['redirect_to'] ) ? $_REQUEST['redirect_to'] : '';
     665    /**
     666     * Filter the registration redirect URL.
     667     *
     668     * @since 3.0.0
     669     *
     670     * @param string $registration_redirect The redirect destination URL.
     671     */
     672    $redirect_to = apply_filters( 'registration_redirect', $registration_redirect );
    499673    login_header(__('Registration Form'), '<p class="message register">' . __('Register For This Site') . '</p>', $errors);
    500674?>
    … …  
    509683        <input type="text" name="user_email" id="user_email" class="input" value="<?php echo esc_attr(wp_unslash($user_email)); ?>" size="25" /></label>
    510684    </p>
    511 <?php do_action('register_form'); ?>
     685    <?php
     686    /**
     687     * Fires following the 'E-mail' field in the user registration form.
     688     *
     689     * @since 2.1.0
     690     */
     691    do_action( 'register_form' );
     692    ?>
    512693    <p id="reg_passmail"><?php _e('A password will be e-mailed to you.') ?></p>
    513694    <br class="clear" />
    … …  
    566747        $user = wp_signon('', $secure_cookie);
    567748
    568     $redirect_to = apply_filters('login_redirect', $redirect_to, isset( $_REQUEST['redirect_to'] ) ? $_REQUEST['redirect_to'] : '', $user);
     749    $requested_redirect_to = isset( $_REQUEST['redirect_to'] ) ? $_REQUEST['redirect_to'] : '';
     750    /**
     751     * Filter the login redirect URL.
     752     *
     753     * @since 3.0.0
     754     *
     755     * @param string           $redirect_to           The redirect destination URL.
     756     * @param string           $requested_redirect_to The requested redirect destination URL passed as a parameter.
     757     * @param WP_User|WP_Error $user                  WP_User object if login was successful, WP_Error object otherwise.
     758     */
     759    $redirect_to = apply_filters( 'login_redirect', $redirect_to, $requested_redirect_to, $user );
    569760
    570761    if ( !is_wp_error($user) && !$reauth ) {
    … …  
    574765            login_header( '', $message ); ?>
    575766            </div>
    576             <?php do_action( 'login_footer' ); ?>
     767            <?php
     768            //duplicate_hook
     769            do_action( 'login_footer' ); ?>
    577770            <?php if ( $customize_login ) : ?>
    578771                <script type="text/javascript">setTimeout( function(){ new wp.customize.Messenger({ url: '<?php echo wp_customize_url(); ?>', channel: 'login' }).send('login') }, 1000 );</script>
    … …  
    619812    }
    620813
     814    /**
     815     * Filter the login page errors.
     816     *
     817     * @since 3.6.0
     818     *
     819     * @param object $errors      WP Error object.
     820     * @param string $redirect_to Redirect destination URL.
     821     */
    621822    $errors = apply_filters( 'wp_login_errors', $errors, $redirect_to );
    622823
    … …  
    641842        <input type="password" name="pwd" id="user_pass" class="input" value="" size="20" /></label>
    642843    </p>
    643 <?php do_action('login_form'); ?>
     844    <?php
     845    /**
     846     * Fires following the 'Password' field in the login form.
     847     *
     848     * @since 2.1.0
     849     */
     850    do_action( 'login_form' );
     851    ?>
    644852    <p class="forgetmenot"><label for="rememberme"><input name="rememberme" type="checkbox" id="rememberme" value="forever" <?php checked( $rememberme ); ?> /> <?php esc_attr_e('Remember Me'); ?></label></p>
    645853    <p class="submit">
    … …  
    659867<?php if ( ! $interim_login ) { ?>
    660868<p id="nav">
    661 <?php if ( ! isset( $_GET['checkemail'] ) || ! in_array( $_GET['checkemail'], array( 'confirm', 'newpass' ) ) ) : ?>
    662     <?php if ( get_option( 'users_can_register' ) ) : ?>
    663         <?php echo apply_filters( 'register', sprintf( '<a href="%s">%s</a>', esc_url( wp_registration_url() ), __( 'Register' ) ) ); ?> |
    664     <?php endif; ?>
     869<?php if ( ! isset( $_GET['checkemail'] ) || ! in_array( $_GET['checkemail'], array( 'confirm', 'newpass' ) ) ) :
     870    if ( get_option( 'users_can_register' ) ) :
     871        $registration_url = sprintf( '<a href="%s">%s</a>', esc_url( wp_registration_url() ), __( 'Register' ) );
     872        //duplicate_hook
     873        echo apply_filters( 'register', $registration_url ) . ' | ';
     874    endif;
     875    ?>
    665876    <a href="<?php echo esc_url( wp_lostpassword_url() ); ?>" title="<?php esc_attr_e( 'Password Lost and Found' ); ?>"><?php _e( 'Lost your password?' ); ?></a>
    666877<?php endif; ?>
Note: See TracChangeset for help on using the changeset viewer.