函数文档

wpmu_new_site_admin_notification()

💡 云策文档标注

概述

wpmu_new_site_admin_notification() 是一个 WordPress 多站点函数,用于在新站点创建时向网络管理员发送电子邮件通知。该函数支持通过过滤器自定义邮件内容和发送行为。

关键要点

  • 函数接受两个必需参数:$site_id(新站点的 ID)和 $user_id(新站点管理员的用户 ID),返回布尔值表示邮件是否成功发送。
  • 使用 'send_new_site_email' 过滤器可以控制是否发送邮件,返回 false 可禁用通知。
  • 使用 'new_site_email' 过滤器可以修改邮件内容,包括收件人、主题、消息和头部。
  • 函数内部处理了本地化切换,根据网络管理员用户或当前站点设置语言环境。
  • 依赖多个 WordPress 核心函数,如 get_site()、get_userdata()、wp_mail() 等,确保正确获取站点和用户数据并发送邮件。

代码示例

function wpmu_new_site_admin_notification( $site_id, $user_id ) {
	$site  = get_site( $site_id );
	$user  = get_userdata( $user_id );
	$email = get_site_option( 'admin_email' );

	if ( ! $site || ! $user || ! $email ) {
		return false;
	}

	if ( ! apply_filters( 'send_new_site_email', true, $site, $user ) ) {
		return false;
	}

	// 本地化切换和邮件构建逻辑
	$new_site_email = apply_filters( 'new_site_email', $new_site_email, $site, $user );

	wp_mail(
		$new_site_email['to'],
		wp_specialchars_decode( $new_site_email['subject'] ),
		$new_site_email['message'],
		$new_site_email['headers']
	);

	return true;
}

注意事项

  • 确保 $site_id 和 $user_id 有效,否则函数可能返回 false。
  • 邮件发送依赖于 wp_mail() 函数,需确保服务器邮件配置正确。
  • 过滤器 'send_new_site_email' 和 'new_site_email' 允许开发者灵活定制通知行为,避免硬编码修改。
  • 函数在 WordPress 5.6.0 版本引入,使用时需检查兼容性。

📄 原文内容

Notifies the Multisite network administrator that a new site was created.

Description

Filter ‘send_new_site_email’ to disable or bypass.

Filter ‘new_site_email’ to filter the contents.

Parameters

$site_idintrequired
Site ID of the new site.
$user_idintrequired
User ID of the administrator of the new site.

Return

bool Whether the email notification was sent.

Source

function wpmu_new_site_admin_notification( $site_id, $user_id ) {
	$site  = get_site( $site_id );
	$user  = get_userdata( $user_id );
	$email = get_site_option( 'admin_email' );

	if ( ! $site || ! $user || ! $email ) {
		return false;
	}

	/**
	 * Filters whether to send an email to the Multisite network administrator when a new site is created.
	 *
	 * Return false to disable sending the email.
	 *
	 * @since 5.6.0
	 *
	 * @param bool    $send Whether to send the email.
	 * @param WP_Site $site Site object of the new site.
	 * @param WP_User $user User object of the administrator of the new site.
	 */
	if ( ! apply_filters( 'send_new_site_email', true, $site, $user ) ) {
		return false;
	}

	$switched_locale = false;
	$network_admin   = get_user_by( 'email', $email );

	if ( $network_admin ) {
		// If the network admin email address corresponds to a user, switch to their locale.
		$switched_locale = switch_to_user_locale( $network_admin->ID );
	} else {
		// Otherwise switch to the locale of the current site.
		$switched_locale = switch_to_locale( get_locale() );
	}

	$subject = sprintf(
		/* translators: New site notification email subject. %s: Network title. */
		__( '[%s] New Site Created' ),
		get_network()->site_name
	);

	$message = sprintf(
		/* translators: New site notification email. 1: User login, 2: Site URL, 3: Site title. */
		__(
			'New site created by %1$s

Address: %2$s
Name: %3$s'
		),
		$user->user_login,
		get_site_url( $site->id ),
		get_blog_option( $site->id, 'blogname' )
	);

	$header = sprintf(
		'From: "%1$s" <%2$s>',
		_x( 'Site Admin', 'email "From" field' ),
		$email
	);

	$new_site_email = array(
		'to'      => $email,
		'subject' => $subject,
		'message' => $message,
		'headers' => $header,
	);

	/**
	 * Filters the content of the email sent to the Multisite network administrator when a new site is created.
	 *
	 * Content should be formatted for transmission via wp_mail().
	 *
	 * @since 5.6.0
	 *
	 * @param array $new_site_email {
	 *     Used to build wp_mail().
	 *
	 *     @type string $to      The email address of the recipient.
	 *     @type string $subject The subject of the email.
	 *     @type string $message The content of the email.
	 *     @type string $headers Headers.
	 * }
	 * @param WP_Site $site         Site object of the new site.
	 * @param WP_User $user         User object of the administrator of the new site.
	 */
	$new_site_email = apply_filters( 'new_site_email', $new_site_email, $site, $user );

	wp_mail(
		$new_site_email['to'],
		wp_specialchars_decode( $new_site_email['subject'] ),
		$new_site_email['message'],
		$new_site_email['headers']
	);

	if ( $switched_locale ) {
		restore_previous_locale();
	}

	return true;
}

Hooks

apply_filters( ‘new_site_email’, array $new_site_email, WP_Site $site, WP_User $user )

Filters the content of the email sent to the Multisite network administrator when a new site is created.

apply_filters( ‘send_new_site_email’, bool $send, WP_Site $site, WP_User $user )

Filters whether to send an email to the Multisite network administrator when a new site is created.

Changelog

Version Description
5.6.0 Introduced.