wp_authenticate()
云策文档标注
概述
wp_authenticate() 是 WordPress 中用于验证用户登录凭证是否有效的可插拔函数。它接受用户名（或邮箱地址）和密码作为参数，返回 WP_User 对象或 WP_Error 对象。
关键要点
- 参数：$username（字符串，必需，用户名或邮箱地址），$password（字符串，必需，用户密码）。
- 返回值：WP_User 对象（凭证有效时）或 WP_Error 对象（凭证无效时）。
- 这是一个可插拔函数，插件可以覆盖其行为。
- 不要与 wp_authenticate action hook 混淆。
- 内部使用 authenticate filter 和 wp_login_failed action 进行扩展。
代码示例
$user = wp_authenticate($username, $password);
if(!is_wp_error($user)) {
$first_name = $user->first_name;
echo "Login credentials are valid. First name is $first_name";
} else {
echo "Invalid login credentials.";
}注意事项
- 函数内部对 $username 使用 sanitize_user() 进行清理，对 $password 使用 trim() 去除空格。
- authenticate filter 允许自定义凭证验证逻辑。
- wp_login_failed action 在登录失败时触发，可用于记录或处理错误。
原文内容
Authenticates a user, confirming the login credentials are valid.
Parameters
$usernamestringrequired-
User’s username or email address.
$passwordstringrequired-
User’s password.
Source
function wp_authenticate(
$username,
#[SensitiveParameter]
$password
) {
$username = sanitize_user( $username );
$password = trim( $password );
/**
* Filters whether a set of user login credentials are valid.
*
* A WP_User object is returned if the credentials authenticate a user.
* WP_Error or null otherwise.
*
* @since 2.8.0
* @since 4.5.0 `$username` now accepts an email address.
*
* @param null|WP_User|WP_Error $user WP_User if the user is authenticated.
* WP_Error or null otherwise.
* @param string $username Username or email address.
* @param string $password User password.
*/
$user = apply_filters( 'authenticate', null, $username, $password );
if ( null === $user || false === $user ) {
/*
* TODO: What should the error message be? (Or would these even happen?)
* Only needed if all authentication handlers fail to return anything.
*/
$user = new WP_Error( 'authentication_failed', __( '<strong>Error:</strong> Invalid username, email address or incorrect password.' ) );
}
$ignore_codes = array( 'empty_username', 'empty_password' );
if ( is_wp_error( $user ) && ! in_array( $user->get_error_code(), $ignore_codes, true ) ) {
$error = $user;
/**
* Fires after a user login has failed.
*
* @since 2.5.0
* @since 4.5.0 The value of `$username` can now be an email address.
* @since 5.4.0 The `$error` parameter was added.
*
* @param string $username Username or email address.
* @param WP_Error $error A WP_Error object with the authentication failure details.
*/
do_action( 'wp_login_failed', $username, $error );
}
return $user;
}
Hooks
- apply_filters( ‘authenticate’, null|WP_User|WP_Error $user, string $username, string $password )
-
Filters whether a set of user login credentials are valid.
- do_action( ‘wp_login_failed’, string $username, WP_Error $error )
-
Fires after a user login has failed.
Skip to note 2 content
Md. Zubaer Ahammed
Check whether credentials are valid or not for a defined user.
$user = wp_authenticate($username, $password); if(!is_wp_error($user)) { $first_name = $user->first_name; echo "Login credentials are valid. First name is $first_name"; } else { echo "Invalid login credentials."; }