云策 WordPress 开发者社区

函数文档

update_option_new_admin_email()

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

概述

update_option_new_admin_email() 是 WordPress 中用于处理站点管理员邮箱地址变更确认的函数。当尝试更改管理员邮箱时，该函数会发送一封确认请求邮件，新邮箱地址在确认前不会生效。

关键要点

  • 函数在管理员邮箱变更时触发，生成确认链接并发送邮件。
  • 使用 md5 哈希和时间戳生成唯一确认链接，确保安全性。
  • 支持国际化，通过 switch_to_user_locale() 切换用户语言环境。
  • 提供 new_admin_email_content 和 new_admin_email_subject 过滤器，允许自定义邮件内容和主题。
  • 邮件中包含占位符（如 ###USERNAME###、###ADMIN_URL###），在发送前动态替换为实际值。
  • 函数从 WordPress 4.9.0 起不再仅限于多站点，适用于所有安装。

代码示例

// 禁用管理员邮箱变更确认通知的示例代码
remove_action( 'add_option_new_admin_email', 'update_option_new_admin_email' );
remove_action( 'update_option_new_admin_email', 'update_option_new_admin_email' );

function wpdocs_update_option_new_admin_email( $old_value, $value ) {
    update_option( 'admin_email', $value );
}
add_action( 'add_option_new_admin_email', 'wpdocs_update_option_new_admin_email', 10, 2 );
add_action( 'update_option_new_admin_email', 'wpdocs_update_option_new_admin_email', 10, 2 );

注意事项

  • 确保新邮箱地址有效（通过 is_email() 验证），否则函数会提前返回。
  • 确认链接通过 adminhash 选项存储，需注意其安全性和过期处理。
  • 使用 wp_mail() 发送邮件，需确保邮件服务配置正确。
📄 原文内容

Sends a confirmation request email when a change of site admin email address is attempted.

Description

The new site admin address will not become active until confirmed.

Parameters

$old_valuestringrequired
The old site admin email address.
$valuestringrequired
The proposed new site admin email address.

Source

function update_option_new_admin_email( $old_value, $value ) {
	if ( get_option( 'admin_email' ) === $value || ! is_email( $value ) ) {
		return;
	}

	$hash            = md5( $value . time() . wp_rand() );
	$new_admin_email = array(
		'hash'     => $hash,
		'newemail' => $value,
	);
	update_option( 'adminhash', $new_admin_email, false );

	$switched_locale = switch_to_user_locale( get_current_user_id() );

	/* translators: Do not translate USERNAME, ADMIN_URL, EMAIL, SITENAME, SITEURL: those are placeholders. */
	$email_text = __(
		'Howdy,

A site administrator (###USERNAME###) recently requested to have the
administration email address changed on this site:
###SITEURL###

To confirm this change, please click on the following link:
###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 site admin 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 proposed new site admin email address.
	 *  - `###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_admin_email {
	 *     Data relating to the new site admin email address.
	 *
	 *     @type string $hash     The secure hash used in the confirmation link URL.
	 *     @type string $newemail The proposed new site admin email address.
	 * }
	 */
	$content = apply_filters( 'new_admin_email_content', $email_text, $new_admin_email );

	$current_user = wp_get_current_user();
	$content      = str_replace( '###USERNAME###', $current_user->user_login, $content );
	$content      = str_replace( '###ADMIN_URL###', esc_url( self_admin_url( 'options.php?adminhash=' . $hash ) ), $content );
	$content      = str_replace( '###EMAIL###', $value, $content );
	$content      = str_replace( '###SITENAME###', wp_specialchars_decode( get_option( 'blogname' ), ENT_QUOTES ), $content );
	$content      = str_replace( '###SITEURL###', home_url(), $content );

	if ( '' !== get_option( 'blogname' ) ) {
		$site_title = wp_specialchars_decode( get_option( 'blogname' ), ENT_QUOTES );
	} else {
		$site_title = parse_url( home_url(), PHP_URL_HOST );
	}

	$subject = sprintf(
		/* translators: New admin email address notification email subject. %s: Site title. */
		__( '[%s] New Admin Email Address' ),
		$site_title
	);

	/**
	 * Filters the subject of the email sent when a change of site admin email address is attempted.
	 *
	 * @since 6.5.0
	 *
	 * @param string $subject Subject of the email.
	 */
	$subject = apply_filters( 'new_admin_email_subject', $subject );

	wp_mail( $value, $subject, $content );

	if ( $switched_locale ) {
		restore_previous_locale();
	}
}

View all references View on Trac View on GitHub

Hooks

apply_filters( ‘new_admin_email_content’, string $email_text, array $new_admin_email )

Filters the text of the email sent when a change of site admin email address is attempted.

apply_filters( ‘new_admin_email_subject’, string $subject )

Filters the subject of the email sent when a change of site admin email address is attempted.

Uses Description
switch_to_user_locale()wp-includes/l10n.php

Switches the translations according to the given user’s locale.
restore_previous_locale()wp-includes/l10n.php

Restores the translations according to the previous locale.
is_email()wp-includes/formatting.php

Verifies that an email is valid.
wp_specialchars_decode()wp-includes/formatting.php

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

Generates a random non-negative number.
wp_get_current_user()wp-includes/pluggable.php

Retrieves the current user object.
wp_mail()wp-includes/pluggable.php

Sends an email, similar to PHP’s mail function.
self_admin_url()wp-includes/link-template.php

Retrieves the URL to the admin area for either the current site or the network depending on context.
__()wp-includes/l10n.php

Retrieves the translation of $text.
esc_url()wp-includes/formatting.php

Checks and cleans a URL.
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.
update_option()wp-includes/option.php

Updates the value of an option that was already added.
get_option()wp-includes/option.php

Retrieves an option value based on an option name.
get_current_user_id()wp-includes/user.php

Gets the current user’s ID.

Show 10 moreShow less

Changelog

Version Description
4.9.0 This function was moved from wp-admin/includes/ms.php so it’s no longer Multisite specific.
3.0.0 Introduced.

User Contributed Notes

  1. Skip to note 2 content


    Codex


    You must log in to vote on the helpfulness of this noteVote results for this note: 0You must log in to vote on the helpfulness of this note

    Disable the confirmation notices when an administrator changes their email address.

    remove_action( 'add_option_new_admin_email', 'update_option_new_admin_email' );
remove_action( 'update_option_new_admin_email', 'update_option_new_admin_email' );

/**
 * Disable the confirmation notices when an administrator
 * changes their email address.
 *
 * @see <a href="http://codex.wordpress.com/Function_Reference/update_option_new_admin_email" rel="nofollow ugc">http://codex.wordpress.com/Function_Reference/update_option_new_admin_email</a>
 */
function wpdocs_update_option_new_admin_email( $old_value, $value ) {

	update_option( 'admin_email', $value );
}
add_action( 'add_option_new_admin_email', 'wpdocs_update_option_new_admin_email', 10, 2 );
add_action( 'update_option_new_admin_email', 'wpdocs_update_option_new_admin_email', 10, 2 );