wpmu_welcome_user_notification()
云策文档标注
概述
wpmu_welcome_user_notification() 是 WordPress 多站点（MU）中的一个函数，用于在用户账户激活成功后发送欢迎邮件通知。该函数支持通过过滤器（Filter）来禁用、修改邮件内容和主题行，确保开发者可以灵活定制通知行为。
关键要点
- 函数用途：发送用户账户激活成功的欢迎邮件通知。
- 参数：$user_id（用户ID，必填）、$password（用户密码，必填）、$meta（注册元数据，可选，默认空数组）。
- 返回值：布尔值，成功返回 true，禁用时返回 false。
- 过滤器：提供 'wpmu_welcome_user_notification' 过滤器来禁用邮件，'update_welcome_user_email' 和 'update_welcome_user_subject' 过滤器来修改邮件内容和主题。
- 邮件内容处理：使用占位符（如 SITE_NAME、USERNAME、PASSWORD、LOGINLINK）动态替换为实际值。
- 本地化支持：通过 switch_to_user_locale() 和 restore_previous_locale() 切换用户语言环境。
- 邮件发送：使用 wp_mail() 函数发送邮件，支持自定义发件人和字符集。
代码示例
// 示例：使用过滤器修改欢迎邮件内容
add_filter( 'update_welcome_user_email', function( $welcome_email, $user_id, $password, $meta ) {
// 自定义邮件内容逻辑
$custom_message = "欢迎加入我们的网站！您的账户已激活。";
return $custom_message;
}, 10, 4 );
// 示例：禁用欢迎邮件
add_filter( 'wpmu_welcome_user_notification', '__return_false' );注意事项
- 该函数仅适用于 WordPress 多站点环境，单站点中可能不适用。
- 邮件内容应格式化为适合 wp_mail() 传输的文本，避免 HTML 格式错误。
- 使用 'wpmu_welcome_user_notification' 过滤器返回 false 可以完全禁用邮件发送，但需确保不影响其他功能。
- 参数 $password 标记为敏感参数，处理时应注意安全，避免日志记录或泄露。
- 函数内部依赖多个 WordPress 核心函数（如 get_userdata、wp_mail 等），确保这些函数在调用时可用。
原文内容
Notifies a user that their account activation has been successful.
Description
Filter ‘wpmu_welcome_user_notification’ to disable or bypass.
Filter ‘update_welcome_user_email’ and ‘update_welcome_user_subject’ to modify the content and subject line of the notification email.
Parameters
$user_idintrequired-
User ID.
$passwordstringrequired-
User password.
$metaarrayoptional-
Signup meta data.
Default:
array()
Source
function wpmu_welcome_user_notification(
$user_id,
#[SensitiveParameter]
$password,
$meta = array()
) {
$current_network = get_network();
/**
* Filters whether to bypass the welcome email after user activation.
*
* Returning false disables the welcome email.
*
* @since MU (3.0.0)
*
* @param int $user_id User ID.
* @param string $password User password.
* @param array $meta Signup meta data. Default empty array.
*/
if ( ! apply_filters( 'wpmu_welcome_user_notification', $user_id, $password, $meta ) ) {
return false;
}
$welcome_email = get_site_option( 'welcome_user_email' );
$user = get_userdata( $user_id );
$switched_locale = switch_to_user_locale( $user_id );
/**
* Filters the content of the welcome email after user activation.
*
* Content should be formatted for transmission via wp_mail().
*
* @since MU (3.0.0)
*
* @param string $welcome_email The message body of the account activation success email.
* @param int $user_id User ID.
* @param string $password User password.
* @param array $meta Signup meta data. Default empty array.
*/
$welcome_email = apply_filters( 'update_welcome_user_email', $welcome_email, $user_id, $password, $meta );
$welcome_email = str_replace( 'SITE_NAME', $current_network->site_name, $welcome_email );
$welcome_email = str_replace( 'USERNAME', $user->user_login, $welcome_email );
$welcome_email = str_replace( 'PASSWORD', $password, $welcome_email );
$welcome_email = str_replace( 'LOGINLINK', wp_login_url(), $welcome_email );
$admin_email = get_site_option( 'admin_email' );
if ( '' === $admin_email ) {
$admin_email = 'support@' . wp_parse_url( network_home_url(), PHP_URL_HOST );
}
$from_name = ( '' !== get_site_option( 'site_name' ) ) ? esc_html( get_site_option( 'site_name' ) ) : 'WordPress';
$message_headers = "From: "{$from_name}" <{$admin_email}>n" . 'Content-Type: text/plain; charset="' . get_option( 'blog_charset' ) . ""n";
$message = $welcome_email;
if ( empty( $current_network->site_name ) ) {
$current_network->site_name = 'WordPress';
}
/* translators: New user notification email subject. 1: Network title, 2: New user login. */
$subject = __( 'New %1$s User: %2$s' );
/**
* Filters the subject of the welcome email after user activation.
*
* @since MU (3.0.0)
*
* @param string $subject Subject of the email.
*/
$subject = apply_filters( 'update_welcome_user_subject', sprintf( $subject, $current_network->site_name, $user->user_login ) );
wp_mail( $user->user_email, wp_specialchars_decode( $subject ), $message, $message_headers );
if ( $switched_locale ) {
restore_previous_locale();
}
return true;
}
Hooks
- apply_filters( ‘update_welcome_user_email’, string $welcome_email, int $user_id, string $password, array $meta )
-
Filters the content of the welcome email after user activation.
- apply_filters( ‘update_welcome_user_subject’, string $subject )
-
Filters the subject of the welcome email after user activation.
- apply_filters( ‘wpmu_welcome_user_notification’, int $user_id, string $password, array $meta )
-
Filters whether to bypass the welcome email after user activation.
Changelog
| Version | Description |
|---|---|
| MU (3.0.0) | Introduced. |