wp_create_user_request() │ WP 4.9.6

Creates and records a user request to perform an action with personal data: exporting or deleting data.

The request is saved as a post of type user_request. This allows creating such requests both for registered users of the site and for guests without an account.

The function cleans up the email and the action name, checks the validity of the data, looks for an existing unfinished request with the same email and action, and then creates a new request post.

The function only creates a request. It does not send the user a confirmation email. To send an email, use wp_send_user_request() after the request is successfully created.

For one email and one action, you cannot create a new request while there is already an unfinished request in status request-pending or request-confirmed.

Uses: _wp_privacy_action_request_types(), get_user_by(), wp_insert_post()

No Hooks.

Returns

Int|WP_Error.

  • int — ID of the created request.
  • WP_Error — an error object if the email is invalid, the action is not supported, the status is specified incorrectly, an unfinished request already exists, or the post could not be created.

Usage

wp_create_user_request( $email_address, $action_name, $request_data, $status );
$email_address(string) (required)
User email. This can be the email of a registered user or a guest without an account.
$action_name(string) (required)

The name of the action that needs to be confirmed. Allowed values: export_personal_data and remove_personal_data.

Only supported action types can be passed in $action_name: export_personal_data or remove_personal_data. Other values will result in an invalid_action error.

$request_data(array)
Additional data to store along with the request and pass to handlers after confirmation.
Default: []
$status(string)
Request status. You can specify pending or confirmed.
Default: 'pending'

Examples

0

#1 Creating a request to export personal data

Creates a request to export personal data for the specified email.

$request_id = wp_create_user_request(
	'[email protected]',
	'export_personal_data'
);

if ( is_wp_error( $request_id ) ) {
	wp_die( $request_id->get_error_message() );
}

echo 'Request created. ID: ' . esc_html( $request_id );
0

#2 Creation of a request and sending a confirmation email

After creating the request, sends the user a confirmation email of the action.

$request_id = wp_create_user_request(
	'[email protected]',
	'remove_personal_data'
);

if ( is_wp_error( $request_id ) ) {
	wp_die( $request_id->get_error_message() );
}

$result = wp_send_user_request( $request_id );

if ( is_wp_error( $result ) ) {
	wp_die( $result->get_error_message() );
}

echo 'Confirmation email sent.';
0

#3 Creating a Confirmed Request

Creates a request immediately in the confirmed status.

$request_id = wp_create_user_request(
	'[email protected]',
	'export_personal_data',
	[
		'source' => 'custom-form',
	],
	'confirmed'
);

if ( is_wp_error( $request_id ) ) {
	wp_die( $request_id->get_error_message() );
}

echo 'Confirmed request created.';
0

#4 Error handling for a repeated request

Shows how to separately handle the case when an unfinished request already exists.

$request_id = wp_create_user_request(
	'[email protected]',
	'remove_personal_data'
);

if ( is_wp_error( $request_id ) ) {
	if ( 'duplicate_request' === $request_id->get_error_code() ) {
		echo 'An unfinished request already exists for this email.';
	} else {
		echo esc_html( $request_id->get_error_message() );
	}
}

Changelog

Since 4.9.6 Introduced.
Since 5.7.0 Added the $status parameter.

wp_create_user_request() code WP 7.0

wp-includes/user.php 
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;
}

Other