Using WordPress ‘lostpassword_post’ PHP action

by

The lostpassword_post WordPress PHP action fires before errors are returned from a password reset request. It can be used to modify or add custom error handling when a user submits a password reset request.

Usage

add_action('lostpassword_post', 'my_custom_lostpassword_post', 10, 2);

function my_custom_lostpassword_post($errors, $user_data) {
    // your custom code here
    return $errors;
}

Parameters

  • $errors: WP_Error – A WP_Error object containing any errors generated by using invalid credentials.
  • $user_data: WP_User|false – WP_User object if found, false if the user does not exist.

More information

See WordPress Developer Resources: lostpassword_post

Examples

Display a custom error message for invalid email

In this example, we will display a custom error message when a user submits an invalid email address for a password reset.

add_action('lostpassword_post', 'my_custom_lostpassword_post', 10, 2);

function my_custom_lostpassword_post($errors, $user_data) {
    if (!is_email($_POST['user_login'])) {
        $errors->add('invalid_email', '<strong>ERROR</strong>: Please enter a valid email address.');
    }
    return $errors;
}

Limit password reset requests by IP address

In this example, we will limit the number of password reset requests per IP address to prevent spam or abuse.

add_action('lostpassword_post', 'limit_password_reset_requests', 10, 2);

function limit_password_reset_requests($errors, $user_data) {
    $ip_address = $_SERVER['REMOTE_ADDR'];
    $max_requests = 5;
    $request_count = get_transient('password_reset_requests_' . $ip_address);

    if ($request_count >= $max_requests) {
        $errors->add('too_many_requests', '<strong>ERROR</strong>: Too many password reset requests from your IP address.');
    } else {
        set_transient('password_reset_requests_' . $ip_address, $request_count + 1, 60 * 60);
    }
    return $errors;
}

Add a custom error message for non-existent users

In this example, we will display a custom error message when a user submits a non-existent email address or username for a password reset.

add_action('lostpassword_post', 'custom_error_for_nonexistent_user', 10, 2);

function custom_error_for_nonexistent_user($errors, $user_data) {
    if (!$user_data) {
        $errors->add('nonexistent_user', '<strong>ERROR</strong>: There is no user registered with that email address or username.');
    }
    return $errors;
}

Log password reset request errors

In this example, we will log all password reset request errors for further analysis or debugging purposes.

add_action('lostpassword_post', 'log_password_reset_request_errors', 10, 2);

function log_password_reset_request_errors($errors, $user_data) {
    if ($errors->get_error_codes()) {
        error_log('Password reset request errors: ' . json_encode($errors->get_error_messages()));
    }
    return $errors;
}

Require a specific domain for password reset requests

In this example, we will restrict password reset requests to email addresses from a specific domain.

add_action('lostpassword_post', 'require_specific_domain', 10, 2);

function require_specific_domain($errors, $user_data) {
    $allowed_domain = 'example.com';

    if ($user_data) {
        $email_domain = substr(strrchr($user_data->user_email, "@"), 1);

        if ($email_domain !== $allowed_domain) {
            $errors->add('invalid_domain', '<strong>ERROR</strong>: Only users with an ' . $allowed_domain . ' email address can reset their password.');
        }
    }
    return $errors;
}