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

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

/**
 * Authenticates a user using the email and password.
 *
 * @since 4.5.0
 *
 * @param WP_User|WP_Error|null $user     WP_User or WP_Error object if a previous
 *                                        callback failed authentication.
 * @param string                $email    Email address for authentication.
 * @param string                $password Password for authentication.
 * @return WP_User|WP_Error WP_User on success, WP_Error on failure.
 */
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;
	}

Changelog

VersionDescription
4.5.0Introduced.

User Contributed Notes

  1. Skip to note 2 content

    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.