WordPress.org
Get WordPress
WordPress.org

WordPress Developer Resources

wp_authenticate_email_password()

wp_authenticate_email_password( WP_User|WP_Error|null $user, string $email, string $password ): WP_User|WP_Error

In this article

Back to top

Authenticates a user using the email and password.

Parameters

$userWP_User|WP_Error|nullrequired
WP_User or WP_Error object if a previous callback failed authentication.
$emailstringrequired
Email address for authentication.
$passwordstringrequired
Password for authentication.

Return

WP_User|WP_Error WP_User on success, WP_Error on failure.

Source

function wp_authenticate_email_password(	$user,	$email,	#[\SensitiveParameter]	$password ) {	if ( $user instanceof WP_User ) {	return $user;	}	if ( empty( $email ) || empty( $password ) ) {	if ( is_wp_error( $user ) ) {	return $user;	}	$error = new WP_Error();	if ( empty( $email ) ) {	// Uses 'empty_username' for back-compat with wp_signon().	$error->add( 'empty_username', __( '<strong>Error:</strong> The email field is empty.' ) );	}	if ( empty( $password ) ) {	$error->add( 'empty_password', __( '<strong>Error:</strong> The password field is empty.' ) );	}	return $error;	}	if ( ! is_email( $email ) ) {	return $user;	}	$user = get_user_by( 'email', $email );	if ( ! $user ) {	return new WP_Error(	'invalid_email',	__( 'Unknown email address. Check again or try your username.' )	);	}	/** This filter is documented in wp-includes/user.php */	$user = apply_filters( 'wp_authenticate_user', $user, $password );	if ( is_wp_error( $user ) ) {	return $user;	}	$valid = wp_check_password( $password, $user->user_pass, $user->ID );	if ( ! $valid ) {	return new WP_Error(	'incorrect_password',	sprintf(	/* translators: %s: Email address. */	__( '<strong>Error:</strong> The password you entered for the email address %s is incorrect.' ),	'<strong>' . $email . '</strong>'	) .	' <a href="' . wp_lostpassword_url() . '">' .	__( 'Lost your password?' ) .	'</a>'	);	}	if ( wp_password_needs_rehash( $user->user_pass, $user->ID ) ) {	wp_set_password( $password, $user->ID );	}	return $user; }

View all references View on Trac View on GitHub

Hooks

apply_filters( ‘wp_authenticate_user’, WP_User|WP_Error $user, string $password )

Filters whether the given user can be authenticated with the provided password.

UsesDescription
wp_password_needs_rehash()wp-includes/pluggable.php

Checks whether a password hash needs to be rehashed.

is_email()wp-includes/formatting.php

Verifies that an email is valid.

wp_set_password()wp-includes/pluggable.php

Updates the user’s password with a new hashed one.

wp_check_password()wp-includes/pluggable.php

Checks a plaintext password against a hashed password.

get_user_by()wp-includes/pluggable.php

Retrieves user info by a given field.

wp_lostpassword_url()wp-includes/general-template.php

Returns the URL that allows the user to reset the lost password.

apply_filters()wp-includes/plugin.php

Calls the callback functions that have been added to a filter hook.

is_wp_error()wp-includes/load.php

Checks whether the given variable is a WordPress Error.

WP_Error::__construct()wp-includes/class-wp-error.php

Initializes the error.

Show 4 moreShow less

Changelog

VersionDescription
4.5.0Introduced.

User Contributed Notes

  1. Skip to note 2 content
    timrobinson33
    You must log in to vote on the helpfulness of this noteVote results for this note: -2You must log in to vote on the helpfulness of this note

    If the email parameter is not a valid email address (e.g. does not contain an @ sign), wp_authenticate_email_password will not return WP_Error; it will return NULL

You must log in before being able to contribute a note or feedback.