云策 WordPress 开发者社区

函数文档

wp_authenticate_email_password()

查看官方原文 ↗
💡 云策文档标注

概述

wp_authenticate_email_password() 是 WordPress 中用于通过电子邮件和密码验证用户身份的函数。它接收电子邮件地址和密码作为参数，返回 WP_User 对象表示成功，或 WP_Error 对象表示失败。

关键要点

  • 函数参数包括 $user（WP_User 或 WP_Error 对象，可为 null）、$email（字符串，电子邮件地址）和 $password（字符串，密码）。
  • 返回值为 WP_User 或 WP_Error 对象，成功时返回用户对象，失败时返回错误对象。
  • 函数内部会检查电子邮件和密码是否为空，验证电子邮件格式，并通过 get_user_by() 查找用户。
  • 使用 wp_check_password() 验证密码，并可能通过 wp_password_needs_rehash() 和 wp_set_password() 更新密码哈希。
  • 应用了 wp_authenticate_user 过滤器，允许开发者自定义用户验证逻辑。

代码示例

function wp_authenticate_email_password(
    $user,
    $email,
    #[SensitiveParameter]
    $password
) {
    // 函数实现代码，包括参数检查、用户查找和密码验证等。
}

注意事项

  • 如果电子邮件地址无效（如不包含 @ 符号），函数不会返回 WP_Error，而是返回传入的 $user 参数值（例如 null）。
  • 函数在 WordPress 4.5.0 版本中引入，是核心身份验证流程的一部分。
📄 原文内容

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.

Uses Description
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.
__()wp-includes/l10n.php

Retrieves the translation of $text.
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 5 moreShow less

Changelog

Version Description
4.5.0 Introduced.

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