概述

wp_create_user_request() 函数用于创建并记录用户请求以执行特定操作，例如个人数据导出或删除。请求存储在名为 user_request 的自定义文章类型中，适用于注册用户和非注册用户。

关键要点

• 函数接受四个参数：$email_address（必填，用户邮箱地址）、$action_name（必填，操作名称）、$request_data（可选，请求数据数组，默认为空数组）和 $status（可选，请求状态，默认为 'pending'）。
• 返回值为请求 ID（整数）或 WP_Error 对象（失败时）。
• 函数内部进行邮箱验证、操作名称检查、状态验证和重复请求检测，确保数据安全性和唯一性。
• 使用 wp_insert_post() 将请求存储为 user_request 文章类型，其中 post_name 存储操作名称，post_title 存储邮箱地址。

代码示例

function wp_create_user_request( $email_address = '', $action_name = '', $request_data = array(), $status = 'pending' ) {
    $email_address = sanitize_email( $email_address );
    $action_name   = sanitize_key( $action_name );

    if ( ! is_email( $email_address ) ) {
        return new WP_Error( 'invalid_email', __( 'Invalid email address.' ) );
    }

    if ( ! in_array( $action_name, _wp_privacy_action_request_types(), true ) ) {
        return new WP_Error( 'invalid_action', __( 'Invalid action name.' ) );
    }

    if ( ! in_array( $status, array( 'pending', 'confirmed' ), true ) ) {
        return new WP_Error( 'invalid_status', __( 'Invalid request status.' ) );
    }

    $user    = get_user_by( 'email', $email_address );
    $user_id = $user && ! is_wp_error( $user ) ? $user->ID : 0;

    // Check for duplicates.
    $requests_query = new WP_Query(
        array(
            'post_type'     => 'user_request',
            'post_name__in' => array( $action_name ), // Action name stored in post_name column.
            'title'         => $email_address,        // Email address stored in post_title column.
            'post_status'   => array(
                'request-pending',
                'request-confirmed',
            ),
            'fields'        => 'ids',
        )
    );

    if ( $requests_query->found_posts ) {
        return new WP_Error( 'duplicate_request', __( 'An incomplete personal data request for this email address already exists.' ) );
    }

    $request_id = wp_insert_post(
        array(
            'post_author'   => $user_id,
            'post_name'     => $action_name,
            'post_title'    => $email_address,
            'post_content'  => wp_json_encode( $request_data ),
            'post_status'   => 'request-' . $status,
            'post_type'     => 'user_request',
            'post_date'     => current_time( 'mysql', false ),
            'post_date_gmt' => current_time( 'mysql', true ),
        ),
        true
    );

    return $request_id;
}

注意事项

• 操作名称必须通过 _wp_privacy_action_request_types() 验证，确保是有效的个人数据请求类型。
• 状态参数仅支持 'pending' 或 'confirmed'，否则返回 WP_Error。
• 重复请求检测基于邮箱地址和操作名称，防止创建重复的个人数据请求。
• 函数在 WordPress 4.9.6 中引入，5.7.0 版本添加了 $status 参数。