wp_create_user_request( string $email_address = '', string $action_name = '', array $request_data = array() )

Create and log a user request to perform a specific action.

Description

Requests are stored inside a post type named user_request since they can apply to both users on the site, or guests without a user account.

Parameters

$email_address

(string) (Optional) User email address. This can be the address of a registered or non-registered user.

Default value: ''

$action_name

(string) (Optional) Name of the action that is being confirmed. Required.

Default value: ''

$request_data

(array) (Optional) Misc data you want to send with the verification request and pass to the actions once the request is confirmed.

Default value: array()

Return

(int|WP_Error) Returns the request ID if successful, or a WP_Error object on failure.

Source

File: wp-includes/user.php 

function wp_create_user_request( $email_address = '', $action_name = '', $request_data = array() ) {
	$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 ( ! $action_name ) {
		return new WP_Error( 'invalid_action', __( 'Invalid action name.' ) );
	}

	$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'   => 'any',
		'fields'        => 'ids',
	) );

	if ( $requests_query->found_posts ) {
		return new WP_Error( 'duplicate_request', __( 'A 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-pending',
		'post_type'     => 'user_request',
		'post_date'     => current_time( 'mysql', false ),
		'post_date_gmt' => current_time( 'mysql', true ),
	), true );

	return $request_id;
}

Expand Source Code View on GitHub

Related

Uses

Uses
Uses Description
wp-includes/l10n.php: __()

Retrieve the translation of $text.
wp-includes/class-wp-query.php: WP_Query::__construct()

Constructor.
wp-includes/pluggable.php: get_user_by()

Retrieve user info by a given field
wp-includes/class-wp-error.php: WP_Error::__construct()

Initialize the error.
wp-includes/post.php: wp_insert_post()

Insert or update a post.
wp-includes/formatting.php: sanitize_email()

Strips out all characters that are not allowable in an email.
wp-includes/formatting.php: is_email()

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

Sanitizes a string key.
wp-includes/load.php: is_wp_error()

Check whether variable is a ClassicPress Error.
wp-includes/functions.php: wp_json_encode()

Encode a variable into JSON, with some sanity checks.
wp-includes/functions.php: current_time()

Retrieve the current time based on specified type.
Show 6 more uses Hide more uses

Changelog

Changelog
Version Description
WP-4.9.6 Introduced.