send_confirmation_on_profile_email()
云策文档标注
概述
send_confirmation_on_profile_email() 函数在用户尝试更改电子邮件地址时发送确认请求邮件。它验证用户身份和电子邮件有效性，生成安全哈希并更新用户元数据，然后通过 wp_mail() 发送包含确认链接的邮件。
关键要点
- 函数在用户个人资料页面尝试更改电子邮件地址时触发，发送确认邮件以确保安全性。
- 验证当前用户 ID 与 POST 数据中的 user_id 匹配，防止未授权更改。
- 检查新电子邮件地址是否有效（使用 is_email()）且未被其他用户使用（使用 email_exists()），否则添加错误到 WP_Error 对象。
- 生成基于时间、随机数和电子邮件的 MD5 哈希，存储为 _new_email 用户元数据。
- 使用 new_user_email_content 过滤器允许自定义邮件内容，支持占位符如 ###USERNAME###、###ADMIN_URL### 等。
- 邮件内容通过 str_replace() 动态替换占位符，包括确认链接（使用 self_admin_url()）。
- 发送邮件后，将 POST 中的 email 字段重置为当前用户的原始电子邮件地址。
- 自 WordPress 4.9.0 起，此函数从多站点特定文件移至核心，适用于所有安装类型。
代码示例
// 示例调用场景：在用户个人资料更新处理中
if ( isset( $_POST['email'] ) && $_POST['email'] !== $current_user->user_email ) {
send_confirmation_on_profile_email();
}注意事项
- 函数依赖于全局 $errors 变量，如果未定义，会初始化为 WP_Error 对象。
- 确认链接使用 self_admin_url() 生成，确保指向正确的管理页面（如 profile.php?newuseremail=hash）。
- 邮件主题通过 sprintf() 和翻译函数 __() 本地化，支持多语言站点。
- 在电子邮件已存在时，会删除 _new_email 用户元数据以避免冲突。
- 自版本 3.0.0 引入，4.9.0 后不再仅限于多站点，需注意兼容性。
原文内容
Sends a confirmation request email when a change of user email address is attempted.
Source
function send_confirmation_on_profile_email() {
global $errors;
$current_user = wp_get_current_user();
if ( ! is_object( $errors ) ) {
$errors = new WP_Error();
}
if ( $current_user->ID !== (int) $_POST['user_id'] ) {
return false;
}
if ( $current_user->user_email !== $_POST['email'] ) {
if ( ! is_email( $_POST['email'] ) ) {
$errors->add(
'user_email',
__( '<strong>Error:</strong> The email address is not correct.' ),
array(
'form-field' => 'email',
)
);
return;
}
if ( email_exists( $_POST['email'] ) ) {
$errors->add(
'user_email',
__( '<strong>Error:</strong> The email address is already used.' ),
array(
'form-field' => 'email',
)
);
delete_user_meta( $current_user->ID, '_new_email' );
return;
}
$hash = md5( $_POST['email'] . time() . wp_rand() );
$new_user_email = array(
'hash' => $hash,
'newemail' => $_POST['email'],
);
update_user_meta( $current_user->ID, '_new_email', $new_user_email );
$sitename = wp_specialchars_decode( get_option( 'blogname' ), ENT_QUOTES );
/* translators: Do not translate USERNAME, ADMIN_URL, EMAIL, SITENAME, SITEURL: those are placeholders. */
$email_text = __(
'Howdy ###USERNAME###,
You recently requested to have the email address on your account changed.
If this is correct, please click on the following link to change it:
###ADMIN_URL###
You can safely ignore and delete this email if you do not want to
take this action.
This email has been sent to ###EMAIL###
Regards,
All at ###SITENAME###
###SITEURL###'
);
/**
* Filters the text of the email sent when a change of user email address is attempted.
*
* The following strings have a special meaning and will get replaced dynamically:
*
* - `###USERNAME###` The current user's username.
* - `###ADMIN_URL###` The link to click on to confirm the email change.
* - `###EMAIL###` The new email.
* - `###SITENAME###` The name of the site.
* - `###SITEURL###` The URL to the site.
*
* @since MU (3.0.0)
* @since 4.9.0 This filter is no longer Multisite specific.
*
* @param string $email_text Text in the email.
* @param array $new_user_email {
* Data relating to the new user email address.
*
* @type string $hash The secure hash used in the confirmation link URL.
* @type string $newemail The proposed new email address.
* }
*/
$content = apply_filters( 'new_user_email_content', $email_text, $new_user_email );
$content = str_replace( '###USERNAME###', $current_user->user_login, $content );
$content = str_replace( '###ADMIN_URL###', esc_url( self_admin_url( 'profile.php?newuseremail=' . $hash ) ), $content );
$content = str_replace( '###EMAIL###', $_POST['email'], $content );
$content = str_replace( '###SITENAME###', $sitename, $content );
$content = str_replace( '###SITEURL###', home_url(), $content );
/* translators: New email address notification email subject. %s: Site title. */
wp_mail( $_POST['email'], sprintf( __( '[%s] Email Change Request' ), $sitename ), $content );
$_POST['email'] = $current_user->user_email;
}
}
Hooks
- apply_filters( ‘new_user_email_content’, string $email_text, array $new_user_email )
-
Filters the text of the email sent when a change of user email address is attempted.