云策 WordPress 开发者社区

函数文档

_wp_privacy_send_erasure_fulfillment_notification()

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

概述

_wp_privacy_send_erasure_fulfillment_notification() 是 WordPress 中用于在用户数据擦除请求完成时发送通知邮件的函数。它确保用户知晓其个人数据已被成功擦除，并支持通过多个过滤器钩子自定义邮件内容、主题、收件人和头部。

关键要点

  • 函数接受一个必需的参数 $request_id（隐私请求文章 ID），用于获取关联的 WP_User_Request 对象。
  • 仅在请求状态为 'request-completed' 且未通知过用户时发送邮件，避免重复通知。
  • 支持本地化处理，根据用户或站点默认语言切换邮件内容。
  • 提供多个过滤器钩子（如 user_erasure_fulfillment_email_to、user_erasure_fulfillment_email_subject、user_erasure_fulfillment_email_content 等）允许开发者自定义邮件收件人、主题、内容和头部。
  • 邮件内容包含动态占位符（如 ###SITENAME###、###PRIVACY_POLICY_URL###、###SITEURL###），在发送前会被替换为实际值。
  • 邮件发送成功后，会更新文章元数据 _wp_user_notified 为 true 以标记已通知。

代码示例

function _wp_privacy_send_erasure_fulfillment_notification( $request_id ) {
    $request = wp_get_user_request( $request_id );

    if ( ! ( $request instanceof WP_User_Request ) || 'request-completed' !== $request->status ) {
        return;
    }

    $already_notified = (bool) get_post_meta( $request_id, '_wp_user_notified', true );

    if ( $already_notified ) {
        return;
    }

    // 本地化处理
    if ( ! empty( $request->user_id ) ) {
        $switched_locale = switch_to_user_locale( $request->user_id );
    } else {
        $switched_locale = switch_to_locale( get_locale() );
    }

    $user_email = apply_filters( 'user_erasure_fulfillment_email_to', $request->email, $request );

    $email_data = array(
        'request'            => $request,
        'message_recipient'  => $user_email,
        'privacy_policy_url' => get_privacy_policy_url(),
        'sitename'           => wp_specialchars_decode( get_option( 'blogname' ), ENT_QUOTES ),
        'siteurl'            => home_url(),
    );

    $subject = sprintf( __( '[%s] Erasure Request Fulfilled' ), $email_data['sitename'] );
    $subject = apply_filters( 'user_erasure_fulfillment_email_subject', $subject, $email_data['sitename'], $email_data );

    $content = __( 'Howdy,nnYour request to erase your personal data on ###SITENAME### has been completed.nnIf you have any follow-up questions or concerns, please contact the site administrator.nnRegards,nAll at ###SITENAME###n###SITEURL###' );
    if ( ! empty( $email_data['privacy_policy_url'] ) ) {
        $content = __( 'Howdy,nnYour request to erase your personal data on ###SITENAME### has been completed.nnIf you have any follow-up questions or concerns, please contact the site administrator.nnFor more information, you can also read our privacy policy: ###PRIVACY_POLICY_URL###nnRegards,nAll at ###SITENAME###n###SITEURL###' );
    }
    $content = apply_filters( 'user_erasure_fulfillment_email_content', $content, $email_data );
    $content = str_replace( '###SITENAME###', $email_data['sitename'], $content );
    $content = str_replace( '###PRIVACY_POLICY_URL###', $email_data['privacy_policy_url'], $content );
    $content = str_replace( '###SITEURL###', sanitize_url( $email_data['siteurl'] ), $content );

    $headers = '';
    $headers = apply_filters( 'user_erasure_fulfillment_email_headers', $headers, $subject, $content, $request_id, $email_data );

    $email_sent = wp_mail( $user_email, $subject, $content, $headers );

    if ( $switched_locale ) {
        restore_previous_locale();
    }

    if ( $email_sent ) {
        update_post_meta( $request_id, '_wp_user_notified', true );
    }
}

注意事项

  • 函数依赖于 wp_get_user_request() 获取有效的 WP_User_Request 对象，确保 $request_id 对应一个存在的隐私请求。
  • 使用 apply_filters_deprecated() 处理已弃用的钩子（如 user_confirmed_action_email_content），建议迁移到新钩子以避免未来兼容性问题。
  • 邮件发送使用 wp_mail() 函数，其行为可能受插件或主题影响，需确保邮件系统配置正确。
  • 本地化切换通过 switch_to_user_locale() 或 switch_to_locale() 实现，发送后需恢复原始语言环境。
📄 原文内容

Notifies the user when their erasure request is fulfilled.

Description

Without this, the user would never know if their data was actually erased.

Parameters

$request_idintrequired
The privacy request post ID associated with this request.

Source

function _wp_privacy_send_erasure_fulfillment_notification( $request_id ) {
	$request = wp_get_user_request( $request_id );

	if ( ! ( $request instanceof WP_User_Request ) || 'request-completed' !== $request->status ) {
		return;
	}

	$already_notified = (bool) get_post_meta( $request_id, '_wp_user_notified', true );

	if ( $already_notified ) {
		return;
	}

	// Localize message content for user; fallback to site default for visitors.
	if ( ! empty( $request->user_id ) ) {
		$switched_locale = switch_to_user_locale( $request->user_id );
	} else {
		$switched_locale = switch_to_locale( get_locale() );
	}

	/**
	 * Filters the recipient of the data erasure fulfillment notification.
	 *
	 * @since 4.9.6
	 *
	 * @param string          $user_email The email address of the notification recipient.
	 * @param WP_User_Request $request    The request that is initiating the notification.
	 */
	$user_email = apply_filters( 'user_erasure_fulfillment_email_to', $request->email, $request );

	$email_data = array(
		'request'            => $request,
		'message_recipient'  => $user_email,
		'privacy_policy_url' => get_privacy_policy_url(),
		'sitename'           => wp_specialchars_decode( get_option( 'blogname' ), ENT_QUOTES ),
		'siteurl'            => home_url(),
	);

	$subject = sprintf(
		/* translators: Erasure request fulfilled notification email subject. %s: Site title. */
		__( '[%s] Erasure Request Fulfilled' ),
		$email_data['sitename']
	);

	/**
	 * Filters the subject of the email sent when an erasure request is completed.
	 *
	 * @since 4.9.8
	 * @deprecated 5.8.0 Use 'user_erasure_fulfillment_email_subject' instead.
	 *
	 * @param string $subject    The email subject.
	 * @param string $sitename   The name of the site.
	 * @param array  $email_data {
	 *     Data relating to the account action email.
	 *
	 *     @type WP_User_Request $request            User request object.
	 *     @type string          $message_recipient  The address that the email will be sent to. Defaults
	 *                                               to the value of `$request->email`, but can be changed
	 *                                               by the `user_erasure_fulfillment_email_to` filter.
	 *     @type string          $privacy_policy_url Privacy policy URL.
	 *     @type string          $sitename           The site name sending the mail.
	 *     @type string          $siteurl            The site URL sending the mail.
	 * }
	 */
	$subject = apply_filters_deprecated(
		'user_erasure_complete_email_subject',
		array( $subject, $email_data['sitename'], $email_data ),
		'5.8.0',
		'user_erasure_fulfillment_email_subject'
	);

	/**
	 * Filters the subject of the email sent when an erasure request is completed.
	 *
	 * @since 5.8.0
	 *
	 * @param string $subject    The email subject.
	 * @param string $sitename   The name of the site.
	 * @param array  $email_data {
	 *     Data relating to the account action email.
	 *
	 *     @type WP_User_Request $request            User request object.
	 *     @type string          $message_recipient  The address that the email will be sent to. Defaults
	 *                                               to the value of `$request->email`, but can be changed
	 *                                               by the `user_erasure_fulfillment_email_to` filter.
	 *     @type string          $privacy_policy_url Privacy policy URL.
	 *     @type string          $sitename           The site name sending the mail.
	 *     @type string          $siteurl            The site URL sending the mail.
	 * }
	 */
	$subject = apply_filters( 'user_erasure_fulfillment_email_subject', $subject, $email_data['sitename'], $email_data );

	/* translators: Do not translate SITENAME, SITEURL; those are placeholders. */
	$content = __(
		'Howdy,

Your request to erase your personal data on ###SITENAME### has been completed.

If you have any follow-up questions or concerns, please contact the site administrator.

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

	if ( ! empty( $email_data['privacy_policy_url'] ) ) {
		/* translators: Do not translate SITENAME, SITEURL, PRIVACY_POLICY_URL; those are placeholders. */
		$content = __(
			'Howdy,

Your request to erase your personal data on ###SITENAME### has been completed.

If you have any follow-up questions or concerns, please contact the site administrator.

For more information, you can also read our privacy policy: ###PRIVACY_POLICY_URL###

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

	/**
	 * Filters the body of the data erasure fulfillment notification.
	 *
	 * The email is sent to a user when their data erasure request is fulfilled
	 * by an administrator.
	 *
	 * The following strings have a special meaning and will get replaced dynamically:
	 *
	 *  - `###SITENAME###`           The name of the site.
	 *  - `###PRIVACY_POLICY_URL###` Privacy policy page URL.
	 *  - `###SITEURL###`            The URL to the site.
	 *
	 * @since 4.9.6
	 * @deprecated 5.8.0 Use 'user_erasure_fulfillment_email_content' instead.
	 *                   For user request confirmation email content
	 *                   use 'user_request_confirmed_email_content' instead.
	 *
	 * @param string $content The email content.
	 * @param array  $email_data {
	 *     Data relating to the account action email.
	 *
	 *     @type WP_User_Request $request            User request object.
	 *     @type string          $message_recipient  The address that the email will be sent to. Defaults
	 *                                               to the value of `$request->email`, but can be changed
	 *                                               by the `user_erasure_fulfillment_email_to` filter.
	 *     @type string          $privacy_policy_url Privacy policy URL.
	 *     @type string          $sitename           The site name sending the mail.
	 *     @type string          $siteurl            The site URL sending the mail.
	 * }
	 */
	$content = apply_filters_deprecated(
		'user_confirmed_action_email_content',
		array( $content, $email_data ),
		'5.8.0',
		sprintf(
			/* translators: 1 & 2: Deprecation replacement options. */
			__( '%1$s or %2$s' ),
			'user_erasure_fulfillment_email_content',
			'user_request_confirmed_email_content'
		)
	);

	/**
	 * Filters the body of the data erasure fulfillment notification.
	 *
	 * The email is sent to a user when their data erasure request is fulfilled
	 * by an administrator.
	 *
	 * The following strings have a special meaning and will get replaced dynamically:
	 *
	 *  - `###SITENAME###`           The name of the site.
	 *  - `###PRIVACY_POLICY_URL###` Privacy policy page URL.
	 *  - `###SITEURL###`            The URL to the site.
	 *
	 * @since 5.8.0
	 *
	 * @param string $content The email content.
	 * @param array  $email_data {
	 *     Data relating to the account action email.
	 *
	 *     @type WP_User_Request $request            User request object.
	 *     @type string          $message_recipient  The address that the email will be sent to. Defaults
	 *                                               to the value of `$request->email`, but can be changed
	 *                                               by the `user_erasure_fulfillment_email_to` filter.
	 *     @type string          $privacy_policy_url Privacy policy URL.
	 *     @type string          $sitename           The site name sending the mail.
	 *     @type string          $siteurl            The site URL sending the mail.
	 * }
	 */
	$content = apply_filters( 'user_erasure_fulfillment_email_content', $content, $email_data );

	$content = str_replace( '###SITENAME###', $email_data['sitename'], $content );
	$content = str_replace( '###PRIVACY_POLICY_URL###', $email_data['privacy_policy_url'], $content );
	$content = str_replace( '###SITEURL###', sanitize_url( $email_data['siteurl'] ), $content );

	$headers = '';

	/**
	 * Filters the headers of the data erasure fulfillment notification.
	 *
	 * @since 5.4.0
	 * @deprecated 5.8.0 Use 'user_erasure_fulfillment_email_headers' instead.
	 *
	 * @param string|array $headers    The email headers.
	 * @param string       $subject    The email subject.
	 * @param string       $content    The email content.
	 * @param int          $request_id The request ID.
	 * @param array        $email_data {
	 *     Data relating to the account action email.
	 *
	 *     @type WP_User_Request $request            User request object.
	 *     @type string          $message_recipient  The address that the email will be sent to. Defaults
	 *                                               to the value of `$request->email`, but can be changed
	 *                                               by the `user_erasure_fulfillment_email_to` filter.
	 *     @type string          $privacy_policy_url Privacy policy URL.
	 *     @type string          $sitename           The site name sending the mail.
	 *     @type string          $siteurl            The site URL sending the mail.
	 * }
	 */
	$headers = apply_filters_deprecated(
		'user_erasure_complete_email_headers',
		array( $headers, $subject, $content, $request_id, $email_data ),
		'5.8.0',
		'user_erasure_fulfillment_email_headers'
	);

	/**
	 * Filters the headers of the data erasure fulfillment notification.
	 *
	 * @since 5.8.0
	 *
	 * @param string|array $headers    The email headers.
	 * @param string       $subject    The email subject.
	 * @param string       $content    The email content.
	 * @param int          $request_id The request ID.
	 * @param array        $email_data {
	 *     Data relating to the account action email.
	 *
	 *     @type WP_User_Request $request            User request object.
	 *     @type string          $message_recipient  The address that the email will be sent to. Defaults
	 *                                               to the value of `$request->email`, but can be changed
	 *                                               by the `user_erasure_fulfillment_email_to` filter.
	 *     @type string          $privacy_policy_url Privacy policy URL.
	 *     @type string          $sitename           The site name sending the mail.
	 *     @type string          $siteurl            The site URL sending the mail.
	 * }
	 */
	$headers = apply_filters( 'user_erasure_fulfillment_email_headers', $headers, $subject, $content, $request_id, $email_data );

	$email_sent = wp_mail( $user_email, $subject, $content, $headers );

	if ( $switched_locale ) {
		restore_previous_locale();
	}

	if ( $email_sent ) {
		update_post_meta( $request_id, '_wp_user_notified', true );
	}
}

View all references View on Trac View on GitHub

Hooks

apply_filters_deprecated( ‘user_confirmed_action_email_content’, string $content, array $email_data )

Filters the body of the data erasure fulfillment notification.

apply_filters_deprecated( ‘user_erasure_complete_email_headers’, string|array $headers, string $subject, string $content, int $request_id, array $email_data )

Filters the headers of the data erasure fulfillment notification.

apply_filters_deprecated( ‘user_erasure_complete_email_subject’, string $subject, string $sitename, array $email_data )

Filters the subject of the email sent when an erasure request is completed.

apply_filters( ‘user_erasure_fulfillment_email_content’, string $content, array $email_data )

Filters the body of the data erasure fulfillment notification.

apply_filters( ‘user_erasure_fulfillment_email_headers’, string|array $headers, string $subject, string $content, int $request_id, array $email_data )

Filters the headers of the data erasure fulfillment notification.

apply_filters( ‘user_erasure_fulfillment_email_subject’, string $subject, string $sitename, array $email_data )

Filters the subject of the email sent when an erasure request is completed.

apply_filters( ‘user_erasure_fulfillment_email_to’, string $user_email, WP_User_Request $request )

Filters the recipient of the data erasure fulfillment notification.

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

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

Returns the user request object for the specified request ID.
get_privacy_policy_url()wp-includes/link-template.php

Retrieves the URL to the privacy policy page.
restore_previous_locale()wp-includes/l10n.php

Restores the translations according to the previous locale.
switch_to_locale()wp-includes/l10n.php

Switches the translations according to the given locale.
apply_filters_deprecated()wp-includes/plugin.php

Fires functions attached to a deprecated filter hook.
get_locale()wp-includes/l10n.php

Retrieves the current locale.
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.
update_post_meta()wp-includes/post.php

Updates a post meta field based on the given post ID.
__()wp-includes/l10n.php

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

Sanitizes a URL for database or redirect usage.
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_option()wp-includes/option.php

Retrieves an option value based on an option name.
get_post_meta()wp-includes/post.php

Retrieves a post meta field for the given post ID.

Show 11 moreShow less

Changelog

Version Description
4.9.6 Introduced.