Using WordPress ‘check_password_reset_key()’ PHP function

by

The check_password_reset_key() WordPress PHP function retrieves a user row based on password reset key and login. A key is considered ‘expired’ if it matches the value of the user_activation_key field, after going through the hashing process. This field is now hashed; old values are not accepted but have a different WP_Error code for better user feedback.

Usage

To use check_password_reset_key(), you need to provide two parameters: the reset key and the user login.

$reset_key = 'your-reset-key';
$user_login = 'username';
$user = check_password_reset_key($reset_key, $user_login);

If the function succeeds, it returns the user data. If the key is invalid or expired, it returns a WP_Error instance.

Parameters

  • $key (string) – Required. Hash to validate sending user’s password.
  • $login (string) – Required. The user login.

More information

See WordPress Developer Resources: check_password_reset_key()

This function is part of the WordPress core and is used in the password recovery process.

Examples

Basic Usage

This is a basic usage of check_password_reset_key().

$reset_key = 'your-reset-key';
$user_login = 'username';
$user = check_password_reset_key($reset_key, $user_login);

if ( is_wp_error($user) ) {
    echo 'The key is invalid or expired.';
} else {
    echo 'The key is valid.';
}

With Error Handling

This example shows how to handle errors returned by check_password_reset_key().

$reset_key = 'your-reset-key';
$user_login = 'username';
$user = check_password_reset_key($reset_key, $user_login);

if ( is_wp_error($user) ) {
    echo $user->get_error_message();
} else {
    echo 'The key is valid.';
}

Updating User Password

This example shows how to update the user’s password after validating the reset key.

$reset_key = 'your-reset-key';
$user_login = 'username';
$new_password = 'new-password';
$user = check_password_reset_key($reset_key, $user_login);

if ( is_wp_error($user) ) {
    echo $user->get_error_message();
} else {
    wp_set_password($new_password, $user->ID);
    echo 'Password has been reset.';
}

Redirecting After Successful Reset

This example shows how to redirect the user after a successful password reset.

$reset_key = 'your-reset-key';
$user_login = 'username';
$new_password = 'new-password';
$user = check_password_reset_key($reset_key, $user_login);

if ( is_wp_error($user) ) {
    echo $user->get_error_message();
} else {
    wp_set_password($new_password, $user->ID);
    wp_redirect('http://yourwebsite.com/login');
    exit;
}

Sending an Email After Successful Reset

This example shows how to send an email to the user after a successful password reset.

$reset_key = 'your-reset-key';
$user_login = 'username';
$new_password = 'new-password';
$user = check_password_reset_key($reset_key, $user_login);

if ( is_wp_error($user) ) {
    echo $user->get_error_message();
} else {
    wp_set_password($new_password, $user->ID);
    wp_mail($user->user_email, 'Your password has been reset', 'Your password has been successfully reset.');
    echo 'Password has been reset.';
}

In each of these examples, we use the check_password_reset_key() function to validate the reset key and user login. Depending on the outcome, we handle the error, update the password, redirect the user, or send an email notification.