get_password_reset_key()
云策文档标注
概述
get_password_reset_key() 函数用于为指定用户创建、存储并返回一个密码重置密钥。它验证用户对象，检查密码重置是否允许，生成随机密钥，并通过 Hook 提供扩展点。
关键要点
- 参数 $user 必须是 WP_User 实例，否则返回 WP_Error。
- 返回值为字符串（密码重置密钥）或 WP_Error（错误时）。
- 内部调用 wp_is_password_reset_allowed_for_user() 检查用户是否允许密码重置。
- 使用 wp_generate_password() 生成随机密钥，并存储为 user_activation_key。
- 提供 retrieve_password 和 retrieve_password_key 等 Hook 用于自定义操作。
代码示例
function get_password_reset_key( $user ) {
if ( ! ( $user instanceof WP_User ) ) {
return new WP_Error( 'invalidcombo', __( 'Error: There is no account with that username or email address.' ) );
}
do_action( 'retrieve_password', $user->user_login );
$password_reset_allowed = wp_is_password_reset_allowed_for_user( $user );
if ( ! $password_reset_allowed ) {
return new WP_Error( 'no_password_reset', __( 'Password reset is not allowed for this user' ) );
} elseif ( is_wp_error( $password_reset_allowed ) ) {
return $password_reset_allowed;
}
$key = wp_generate_password( 20, false );
do_action( 'retrieve_password_key', $user->user_login, $key );
$hashed = time() . ':' . wp_fast_hash( $key );
$key_saved = wp_update_user(
array(
'ID' => $user->ID,
'user_activation_key' => $hashed,
)
);
if ( is_wp_error( $key_saved ) ) {
return $key_saved;
}
return $key;
}注意事项
- 自 WordPress 4.4.0 版本引入此函数。
- 使用 do_action_deprecated() 处理已弃用的 'retreive_password' Hook，建议改用 'retrieve_password'。
- 密钥存储为哈希值，结合时间戳以增强安全性。
原文内容
Creates, stores, then returns a password reset key for user.
Parameters
$userWP_Userrequired-
User to retrieve password reset key for.
Source
function get_password_reset_key( $user ) {
if ( ! ( $user instanceof WP_User ) ) {
return new WP_Error( 'invalidcombo', __( '<strong>Error:</strong> There is no account with that username or email address.' ) );
}
/**
* Fires before a new password is retrieved.
*
* Use the 'retrieve_password' hook instead.
*
* @since 1.5.0
* @deprecated 1.5.1 Misspelled. Use 'retrieve_password' hook instead.
*
* @param string $user_login The user login name.
*/
do_action_deprecated( 'retreive_password', array( $user->user_login ), '1.5.1', 'retrieve_password' );
/**
* Fires before a new password is retrieved.
*
* @since 1.5.1
*
* @param string $user_login The user login name.
*/
do_action( 'retrieve_password', $user->user_login );
$password_reset_allowed = wp_is_password_reset_allowed_for_user( $user );
if ( ! $password_reset_allowed ) {
return new WP_Error( 'no_password_reset', __( 'Password reset is not allowed for this user' ) );
} elseif ( is_wp_error( $password_reset_allowed ) ) {
return $password_reset_allowed;
}
// Generate something random for a password reset key.
$key = wp_generate_password( 20, false );
/**
* Fires when a password reset key is generated.
*
* @since 2.5.0
*
* @param string $user_login The username for the user.
* @param string $key The generated password reset key.
*/
do_action( 'retrieve_password_key', $user->user_login, $key );
$hashed = time() . ':' . wp_fast_hash( $key );
$key_saved = wp_update_user(
array(
'ID' => $user->ID,
'user_activation_key' => $hashed,
)
);
if ( is_wp_error( $key_saved ) ) {
return $key_saved;
}
return $key;
}
Hooks
- do_action_deprecated( ‘retreive_password’, string $user_login )
-
Fires before a new password is retrieved.
- do_action( ‘retrieve_password’, string $user_login )
-
Fires before a new password is retrieved.
- do_action( ‘retrieve_password_key’, string $user_login, string $key )
-
Fires when a password reset key is generated.
Changelog
| Version | Description |
|---|---|
| 4.4.0 | Introduced. |