云策 WordPress 开发者社区

函数文档

wp_network_admin_email_change_notification()

查看官方原文 ↗
💡 云策文档标注

概述

wp_network_admin_email_change_notification() 函数在 WordPress 多站点网络中，当网络管理员邮箱地址变更时，向旧邮箱地址发送通知邮件。它处理邮件内容的构建、过滤和发送，并包含可定制的钩子。

关键要点

  • 函数参数包括 $option_name（数据库选项名）、$new_email（新邮箱地址）、$old_email（旧邮箱地址）和 $network_id（网络ID），均为必需。
  • 通过 send_network_admin_email_change_email 过滤器控制是否发送邮件，默认在旧邮箱为空或为默认值时跳过。
  • 邮件内容使用占位符（如 ###OLD_EMAIL###、###NEW_EMAIL###）动态替换，并通过 network_admin_email_change_email 过滤器允许自定义邮件内容。
  • 依赖 wp_mail() 发送邮件，并整合了 get_site_option()、home_url() 等辅助函数。

代码示例

function wp_network_admin_email_change_notification( $option_name, $new_email, $old_email, $network_id ) {
    $send = true;
    if ( empty( $old_email ) || 'you@example.com' === $old_email ) {
        $send = false;
    }
    $send = apply_filters( 'send_network_admin_email_change_email', $send, $old_email, $new_email, $network_id );
    if ( ! $send ) {
        return;
    }
    $email_change_text = __( 'Hi,

This notice confirms that the network admin email address was changed on ###SITENAME###.

The new network admin email address is ###NEW_EMAIL###.

This email has been sent to ###OLD_EMAIL###

Regards,
All at ###SITENAME###
###SITEURL###' );
    $email_change_email = array(
        'to'      => $old_email,
        'subject' => __( '[%s] Network Admin Email Changed' ),
        'message' => $email_change_text,
        'headers' => '',
    );
    $network_name = wp_specialchars_decode( get_site_option( 'site_name' ), ENT_QUOTES );
    $email_change_email = apply_filters( 'network_admin_email_change_email', $email_change_email, $old_email, $new_email, $network_id );
    $email_change_email['message'] = str_replace( '###OLD_EMAIL###', $old_email, $email_change_email['message'] );
    $email_change_email['message'] = str_replace( '###NEW_EMAIL###', $new_email, $email_change_email['message'] );
    $email_change_email['message'] = str_replace( '###SITENAME###', $network_name, $email_change_email['message'] );
    $email_change_email['message'] = str_replace( '###SITEURL###', home_url(), $email_change_email['message'] );
    wp_mail(
        $email_change_email['to'],
        sprintf( $email_change_email['subject'], $network_name ),
        $email_change_email['message'],
        $email_change_email['headers']
    );
}

注意事项

  • 函数自 WordPress 4.9.0 版本引入，适用于多站点环境。
  • 邮件发送逻辑可通过过滤器灵活调整，开发者应确保钩子使用正确以避免冲突。
  • 占位符替换依赖于网络名称和站点URL，需确保相关函数正常工作。
📄 原文内容

Sends an email to the old network admin email address when the network admin email address changes.

Parameters

$option_namestringrequired
The relevant database option name.
$new_emailstringrequired
The new network admin email address.
$old_emailstringrequired
The old network admin email address.
$network_idintrequired
ID of the network.

Source

function wp_network_admin_email_change_notification( $option_name, $new_email, $old_email, $network_id ) {
	$send = true;

	// Don't send the notification for an empty email address or the default 'admin_email' value.
	if ( empty( $old_email ) || 'you@example.com' === $old_email ) {
		$send = false;
	}

	/**
	 * Filters whether to send the network admin email change notification email.
	 *
	 * @since 4.9.0
	 *
	 * @param bool   $send       Whether to send the email notification.
	 * @param string $old_email  The old network admin email address.
	 * @param string $new_email  The new network admin email address.
	 * @param int    $network_id ID of the network.
	 */
	$send = apply_filters( 'send_network_admin_email_change_email', $send, $old_email, $new_email, $network_id );

	if ( ! $send ) {
		return;
	}

	/* translators: Do not translate OLD_EMAIL, NEW_EMAIL, SITENAME, SITEURL: those are placeholders. */
	$email_change_text = __(
		'Hi,

This notice confirms that the network admin email address was changed on ###SITENAME###.

The new network admin email address is ###NEW_EMAIL###.

This email has been sent to ###OLD_EMAIL###

Regards,
All at ###SITENAME###
###SITEURL###'
	);

	$email_change_email = array(
		'to'      => $old_email,
		/* translators: Network admin email change notification email subject. %s: Network title. */
		'subject' => __( '[%s] Network Admin Email Changed' ),
		'message' => $email_change_text,
		'headers' => '',
	);
	// Get network name.
	$network_name = wp_specialchars_decode( get_site_option( 'site_name' ), ENT_QUOTES );

	/**
	 * Filters the contents of the email notification sent when the network admin email address is changed.
	 *
	 * @since 4.9.0
	 *
	 * @param array $email_change_email {
	 *     Used to build wp_mail().
	 *
	 *     @type string $to      The intended recipient.
	 *     @type string $subject The subject of the email.
	 *     @type string $message The content of the email.
	 *         The following strings have a special meaning and will get replaced dynamically:
	 *          - `###OLD_EMAIL###` The old network admin email address.
	 *          - `###NEW_EMAIL###` The new network admin email address.
	 *          - `###SITENAME###`  The name of the network.
	 *          - `###SITEURL###`   The URL to the site.
	 *     @type string $headers Headers.
	 * }
	 * @param string $old_email  The old network admin email address.
	 * @param string $new_email  The new network admin email address.
	 * @param int    $network_id ID of the network.
	 */
	$email_change_email = apply_filters( 'network_admin_email_change_email', $email_change_email, $old_email, $new_email, $network_id );

	$email_change_email['message'] = str_replace( '###OLD_EMAIL###', $old_email, $email_change_email['message'] );
	$email_change_email['message'] = str_replace( '###NEW_EMAIL###', $new_email, $email_change_email['message'] );
	$email_change_email['message'] = str_replace( '###SITENAME###', $network_name, $email_change_email['message'] );
	$email_change_email['message'] = str_replace( '###SITEURL###', home_url(), $email_change_email['message'] );

	wp_mail(
		$email_change_email['to'],
		sprintf(
			$email_change_email['subject'],
			$network_name
		),
		$email_change_email['message'],
		$email_change_email['headers']
	);
}

View all references View on Trac View on GitHub

Hooks

apply_filters( ‘network_admin_email_change_email’, array $email_change_email, string $old_email, string $new_email, int $network_id )

Filters the contents of the email notification sent when the network admin email address is changed.

apply_filters( ‘send_network_admin_email_change_email’, bool $send, string $old_email, string $new_email, int $network_id )

Filters whether to send the network admin email change notification email.

Uses Description
wp_specialchars_decode()wp-includes/formatting.php

Converts a number of HTML entities into their special characters.
wp_mail()wp-includes/pluggable.php

Sends an email, similar to PHP’s mail function.
__()wp-includes/l10n.php

Retrieves the translation of $text.
home_url()wp-includes/link-template.php

Retrieves the URL for the current site where the front end is accessible.
apply_filters()wp-includes/plugin.php

Calls the callback functions that have been added to a filter hook.
get_site_option()wp-includes/option.php

Retrieve an option value for the current network based on name of option.

Show 4 moreShow less

Changelog

Version Description
4.9.0 Introduced.