wp_check_password()
云策文档标注
概述
wp_check_password() 函数用于比较明文密码与哈希密码是否匹配，支持多种哈希算法，并可被插件覆盖或通过过滤器自定义。
关键要点
- 函数用途：验证明文密码与哈希密码的一致性，不仅限于用户密码，也可用于其他类型密码检查。
- 参数说明：接受三个参数：$password（明文密码）、$hash（哈希密码）、$user_id（可选用户ID）。
- 返回值：返回布尔值，密码匹配时返回 true，否则返回 false。
- 算法支持：自动处理多种哈希格式，包括 bcrypt（默认）、phpass 和 md5 等，基于哈希前缀进行识别。
- 可扩展性：可通过插件重写函数或使用 apply_filters('check_password') 钩子自定义验证逻辑。
- 安全限制：密码长度超过 4096 字符时直接返回 false，不支持超长密码。
代码示例
$user = get_user_by( 'login', $username );
if ( $user && wp_check_password( $pass, $user->data->user_pass, $user->ID ) ) {
echo "That's it";
} else {
echo "Nope";
}注意事项
- 函数可能被插件覆盖，若无重写则使用默认实现。
- 从 WordPress 6.8.0 起，默认使用 bcrypt 哈希，旧密码可能仍使用 phpass 或 md5，函数会自动兼容处理。
- 用户ID参数可选，用于关联特定用户，但并非必需，插件可处理无用户ID的密码。
原文内容
Checks a plaintext password against a hashed password.
Description
Note that this function may be used to check a value that is not a user password.
A plugin may use this function to check a password of a different type, and there may not always be a user ID associated with the password.
For integration with other applications, this function can be overwritten to instead use the other package password hashing algorithm.
Parameters
$passwordstringrequired-
Plaintext password.
$hashstringrequired-
Hash of the password to check against.
$user_idstring|intoptional-
ID of a user associated with the password.
Source
function wp_check_password(
#[SensitiveParameter]
$password,
$hash,
$user_id = ''
) {
global $wp_hasher;
if ( strlen( $hash ) <= 32 ) {
// Check the hash using md5 regardless of the current hashing mechanism.
$check = hash_equals( $hash, md5( $password ) );
} elseif ( ! empty( $wp_hasher ) ) {
// Check the password using the overridden hasher.
$check = $wp_hasher->CheckPassword( $password, $hash );
} elseif ( strlen( $password ) > 4096 ) {
// Passwords longer than 4096 characters are not supported.
$check = false;
} elseif ( str_starts_with( $hash, '$wp' ) ) {
// Check the password using the current prefixed hash.
$password_to_verify = base64_encode( hash_hmac( 'sha384', $password, 'wp-sha384', true ) );
$check = password_verify( $password_to_verify, substr( $hash, 3 ) );
} elseif ( str_starts_with( $hash, '$P$' ) ) {
// Check the password using phpass.
require_once ABSPATH . WPINC . '/class-phpass.php';
$check = ( new PasswordHash( 8, true ) )->CheckPassword( $password, $hash );
} else {
// Check the password using compat support for any non-prefixed hash.
$check = password_verify( $password, $hash );
}
/**
* Filters whether the plaintext password matches the hashed password.
*
* @since 2.5.0
* @since 6.8.0 Passwords are now hashed with bcrypt by default.
* Old passwords may still be hashed with phpass or md5.
*
* @param bool $check Whether the passwords match.
* @param string $password The plaintext password.
* @param string $hash The hashed password.
* @param string|int $user_id Optional ID of a user associated with the password.
* Can be empty.
*/
return apply_filters( 'check_password', $check, $password, $hash, $user_id );
}
Hooks
- apply_filters( ‘check_password’, bool $check, string $password, string $hash, string|int $user_id )
-
Filters whether the plaintext password matches the hashed password.
Skip to note 2 content
Codex
Example
$user = get_user_by( 'login', $username ); if ( $user && wp_check_password( $pass, $user->data->user_pass, $user->ID ) ) { echo "That's it"; } else { echo "Nope"; }