retrieve_password( string $user_login = '' ): true|WP_Error

Parameters

$user_loginstringoptional

Username to send a password retrieval email for. Defaults to $_POST['user_login'] if not set.Default: ''

Return

true|WP_Error

True when finished, WP_Error object on error.

Hooks fired · 7

7 hooks fire while retrieve_password() runs, in this order:

1. 1
   apply_filters( lostpassword_user_data )filterline 3208 (+38 into the body)

   Filters the user data during a password reset request.

2. 2
   do_action( lostpassword_post )actionline 3221 (+51 into the body)

   Fires before errors are returned from a password reset request.

3. 3
   apply_filters( lostpassword_errors )filterline 3238 (+68 into the body)

   Filters the errors encountered on a password reset request.

4. 4
   apply_filters( send_retrieve_password_email )filterline 3260 (+90 into the body)

   Filters whether to send the retrieve password email.

5. 5
   apply_filters( retrieve_password_title )filterline 3329 (+159 into the body)

   Filters the subject of the password reset email.

6. 6
   apply_filters( retrieve_password_message )filterline 3344 (+174 into the body)

   Filters the message body of the password reset mail.

7. 7
   apply_filters( retrieve_password_notification_email )filterline 3379 (+209 into the body)

   Filters the contents of the reset password notification email sent to the user.

Uses · 19

• wp_unslash()Removes slashes from a string or recursively removes slashes from strings within an array.
• __()Retrieves the translation of $text.
• get_user_by()Retrieves user info by a given field.
• apply_filters()Calls the callback functions that have been added to a filter hook.
• do_action()Calls the callback functions that have been added to an action hook.
• get_password_reset_key()Creates, stores, then returns a password reset key for user.
• is_wp_error()Checks whether the given variable is a WordPress Error.
• get_user_locale()Retrieves the locale of a user.
• switch_to_user_locale()Switches the translations according to the given user's locale.
• is_multisite()Determines whether Multisite is enabled.
• get_network()Retrieves network data given a network ID or network object.
• wp_specialchars_decode()Converts a number of HTML entities into their special characters.

Used by · 1

• wp_ajax_send_password_reset()Handles sending a password reset link via AJAX.

Source

View on Trac ↗View on GitHub ↗

3170function retrieve_password( $user_login = '' ) {3171	$errors    = new WP_Error();3172	$user_data = false;3173 3174	// Use the passed $user_login if available, otherwise use $_POST['user_login'].3175	if ( ! $user_login && ! empty( $_POST['user_login'] ) ) {3176		$user_login = $_POST['user_login'];3177	}3178 3179	$user_login = trim( wp_unslash( $user_login ) );3180 3181	if ( empty( $user_login ) ) {3182		$errors->add( 'empty_username', __( '<strong>Error:</strong> Please enter a username or email address.' ) );3183	} elseif ( strpos( $user_login, '@' ) ) {3184		$user_data = get_user_by( 'email', $user_login );3185 3186		if ( empty( $user_data ) ) {3187			$user_data = get_user_by( 'login', $user_login );3188		}3189 3190		if ( empty( $user_data ) ) {3191			$errors->add( 'invalid_email', __( '<strong>Error:</strong> There is no account with that username or email address.' ) );3192		}3193	} else {3194		$user_data = get_user_by( 'login', $user_login );3195	}3196 3197	/**3198	 * Filters the user data during a password reset request.3199	 *3200	 * Allows, for example, custom validation using data other than username or email address.3201	 *3202	 * @since 5.7.03203	 *3204	 * @param WP_User|false $user_data WP_User object if found, false if the user does not exist.3205	 * @param WP_Error      $errors    A WP_Error object containing any errors generated3206	 *                                 by using invalid credentials.3207	 */3208	$user_data = apply_filters( 'lostpassword_user_data', $user_data, $errors );3209 3210	/**3211	 * Fires before errors are returned from a password reset request.3212	 *3213	 * @since 2.1.03214	 * @since 4.4.0 Added the `$errors` parameter.3215	 * @since 5.4.0 Added the `$user_data` parameter.3216	 *3217	 * @param WP_Error      $errors    A WP_Error object containing any errors generated3218	 *                                 by using invalid credentials.3219	 * @param WP_User|false $user_data WP_User object if found, false if the user does not exist.3220	 */3221	do_action( 'lostpassword_post', $errors, $user_data );3222 3223	/**3224	 * Filters the errors encountered on a password reset request.3225	 *3226	 * The filtered WP_Error object may, for example, contain errors for an invalid3227	 * username or email address. A WP_Error object should always be returned,3228	 * but may or may not contain errors.3229	 *3230	 * If any errors are present in $errors, this will abort the password reset request.3231	 *3232	 * @since 5.5.03233	 *3234	 * @param WP_Error      $errors    A WP_Error object containing any errors generated3235	 *                                 by using invalid credentials.3236	 * @param WP_User|false $user_data WP_User object if found, false if the user does not exist.3237	 */3238	$errors = apply_filters( 'lostpassword_errors', $errors, $user_data );3239 3240	if ( $errors->has_errors() ) {3241		return $errors;3242	}3243 3244	if ( ! $user_data ) {3245		$errors->add( 'invalidcombo', __( '<strong>Error:</strong> There is no account with that username or email address.' ) );3246		return $errors;3247	}3248 3249	/**

History

Introduced in 2.5.0. Unchanged from 6.7.7 through 7.1.0.

1. 6.7.7
2. 6.8.8
3. 6.9.7
4. 7.0.4
5. 7.1.0

Signature, return type and hooks compared across 5 parsed releases.

About this page

Parsed data

Generated from the wordpress-develop 6.8.8 tag, from src/wp-includes/user.php, and regenerated for each WordPress release so it tracks the code rather than a snapshot of it.

Corrections

Something wrong on this page? Report it and it gets fixed in the next regeneration.