wp_insert_user()WP 2.0.0

Creates a WordPress user in the Database.

IMPORTANT! You shouldn't update the user with this function - use wp_update_user() instead.

You shouldn't, because a lot of side-effects appear, for example:

  • The password is not hashed and goes into the database as it is.
  • The date of registration is changed.
  • Deletes email (if it's not specified).

All boolean values in parameters must be passed as a string: 'true' or 'false', because that's how they are written in the meta-fields.

The length of user_url in the database is limited to 100 characters (true for WP 5.8). If this threshold is exceeded, the user will not be created and you will not see any errors.

I just spent 30 minutes to find what the problem was.

The user can be created without email.

If you do not specify the user_email parameter, the user will be created with an empty email address.

Filters with the pre_ prefix are triggered before the filtered value is used, all filters pass the parameter value. A list of such filters:

pre_user_login
pre_user_nicename
pre_user_url
pre_user_email
pre_user_display_name
pre_user_nickname
pre_user_first_name
pre_user_last_name
pre_user_description

Return

Int|WP_Error.

  • The newly created user's ID
  • WP_Error object if the user could not be created:
    • Invalid user ID.
    • Cannot create a user with an empty login name.
    • Username may not be longer than 60 characters.
    • Sorry, that username already exists!
    • Sorry, that username is not allowed.
    • Nicename may not be longer than 50 characters.
    • Sorry, that email address is already used!

Usage template

$userdata = [
	'user_login'           => '',      // (string) Username for logging in.
	'user_nicename'        => '',      // (string) URL-friendly username.
	'user_url'             => '',      // (string) User URL.
	'user_email'           => '',      // (string) The user's email address.
	'display_name'         => '',      // (string) The user's display name. The default is user_login.
	'nickname'             => '',      // (string) User alias. The default is user_login.
	'first_name'           => '',      // (string) Username.
	'last_name'            => '',      // (string) Last name of the user.
	'description'          => '',      // (string) Biographical description of the user.
	'rich_editing'         => 'true',  // (string) Whether to enable rich-editing for the user.
	'syntax_highlighting'  => 'true',  // (string) Whether to enable syntax highlighting for the code editor.
	'comment_shortcuts'    => 'false', // (string) Whether to enable keyboard shortcuts to moderate comments for the user.
	'admin_color'          => 'fresh', // (string) Whether the admin color scheme for the user. The default is 'fresh'.
	'use_ssl'              => 'false', // (string) Whether the user should always access the admin over https.
	'user_registered'      => '',      // (string) User registration date. The format is 'Y-m-d H:i:s'.
	'show_admin_bar_front' => 'true',  // (string) Whether to display the admin bar for the user on the front side of the site.
	'role'                 => '',      // (string) The user's role.
	'locale'               => '',      // (string) User locale.
	'meta_input'           => [],      // (array) [ 'meta_key' => 'meta_value' ]
];

wp_insert_user( $userdata );

Usage

wp_insert_user( $userdata );
$userdata(array|object|WP_User) (required)

An array, object, or WP_User object of user data arguments.

  • ID(int)
    User ID. If supplied, the user will be updated.

  • user_pass(string)
    The plain-text user password.

  • user_login(string)
    The user's login username.

  • user_nicename(string)
    The URL-friendly user name.

  • user_url(string)
    The user URL.

  • user_email(string)
    The user email address.

  • display_name(string)
    The user's display name.
    Default: user's username

  • nickname(string)
    The user's nickname.
    Default: user's username

  • first_name(string)
    The user's first name. For new users, will be used to build the first part of the user's display name if $display_name is not specified.

  • last_name(string)
    The user's last name. For new users, will be used to build the second part of the user's display name if $display_name is not specified.

  • description(string)
    The user's biographical description.

  • rich_editing(string)
    Whether to enable the rich-editor for the user. Accepts 'true' or 'false' as a string literal, not boolean.
    Default: 'true'

  • syntax_highlighting(string)
    Whether to enable the rich code editor for the user. Accepts 'true' or 'false' as a string literal, not boolean.
    Default: 'true'

  • comment_shortcuts(string)
    Whether to enable comment moderation keyboard shortcuts for the user. Accepts 'true' or 'false' as a string literal, not boolean.
    Default: 'false'

  • admin_color(string)
    Admin color scheme for the user.
    Default: 'fresh'

  • use_ssl(true|false)
    Whether the user should always access the admin over https.
    Default: false

  • user_registered(string)
    Date the user registered in UTC. Format is 'Y-m-d H:i:s'.

  • user_activation_key(string)
    Password reset key.
    Default: ''

  • spam(true|false)
    Multisite only. Whether the user is marked as spam.
    Default: false

  • show_admin_bar_front(string)
    Whether to display the Admin Bar for the user on the site's front end. Accepts 'true' or 'false' as a string literal, not boolean.
    Default: 'true'

  • role(string)
    User's role.

  • locale(string)
    User's locale.
    Default: ''

  • meta_input(array)
    Array of custom user meta values keyed by meta key.
    Default: ''

Examples

#1 Create a user

Create a user by the data from $_POST request:

/**
 * New user registration
 */
function new_user_registration(){

	// Let's check the security fields
	if( ! isset( $_POST['nonce'] ) || ! wp_verify_nonce( $_POST['nonce'], 'vb_new_user' ) ){
		die( 'Oooops, try again, but a little later.' );
	}

	// Data sent to $_POST
	$userdata = [
		'user_login' => $_POST['user'],
		'user_pass'  => $_POST['pass'],
		'user_email' => $_POST['mail'],
		'first_name' => $_POST['name'],
		'nickname'   => $_POST['nick'],
	];

	/**
	 * It is not necessary to validate/clean the passed fields,
	 * WP will do it by itself.
	 */

	$user_id = wp_insert_user( $userdata ) ;

	if( ! is_wp_error( $user_id ) ){
		return true;
	}
	else {
		return $user_id->get_error_message();
	}
}

Notes

  • Global. wpdb. $wpdb WordPress database abstraction object.

Changelog

Since 2.0.0 Introduced.
Since 3.6.0 The aim, jabber, and yim fields were removed as default user contact methods for new installations. See wp_get_user_contact_methods().
Since 4.7.0 The locale field can be passed to $userdata.
Since 5.3.0 The user_activation_key field can be passed to $userdata.
Since 5.3.0 The spam field can be passed to $userdata (Multisite only).
Since 5.9.0 The meta_input field can be passed to $userdata to allow addition of user meta data.

Code of wp_insert_user() WP 5.9.3

function wp_insert_user( $userdata ) {
	global $wpdb;

	if ( $userdata instanceof stdClass ) {
		$userdata = get_object_vars( $userdata );
	} elseif ( $userdata instanceof WP_User ) {
		$userdata = $userdata->to_array();
	}

	// Are we updating or creating?
	if ( ! empty( $userdata['ID'] ) ) {
		$user_id       = (int) $userdata['ID'];
		$update        = true;
		$old_user_data = get_userdata( $user_id );

		if ( ! $old_user_data ) {
			return new WP_Error( 'invalid_user_id', __( 'Invalid user ID.' ) );
		}

		// Hashed in wp_update_user(), plaintext if called directly.
		$user_pass = ! empty( $userdata['user_pass'] ) ? $userdata['user_pass'] : $old_user_data->user_pass;
	} else {
		$update = false;
		// Hash the password.
		$user_pass = wp_hash_password( $userdata['user_pass'] );
	}

	$sanitized_user_login = sanitize_user( $userdata['user_login'], true );

	/**
	 * Filters a username after it has been sanitized.
	 *
	 * This filter is called before the user is created or updated.
	 *
	 * @since 2.0.3
	 *
	 * @param string $sanitized_user_login Username after it has been sanitized.
	 */
	$pre_user_login = apply_filters( 'pre_user_login', $sanitized_user_login );

	// Remove any non-printable chars from the login string to see if we have ended up with an empty username.
	$user_login = trim( $pre_user_login );

	// user_login must be between 0 and 60 characters.
	if ( empty( $user_login ) ) {
		return new WP_Error( 'empty_user_login', __( 'Cannot create a user with an empty login name.' ) );
	} elseif ( mb_strlen( $user_login ) > 60 ) {
		return new WP_Error( 'user_login_too_long', __( 'Username may not be longer than 60 characters.' ) );
	}

	if ( ! $update && username_exists( $user_login ) ) {
		return new WP_Error( 'existing_user_login', __( 'Sorry, that username already exists!' ) );
	}

	/**
	 * Filters the list of disallowed usernames.
	 *
	 * @since 4.4.0
	 *
	 * @param array $usernames Array of disallowed usernames.
	 */
	$illegal_logins = (array) apply_filters( 'illegal_user_logins', array() );

	if ( in_array( strtolower( $user_login ), array_map( 'strtolower', $illegal_logins ), true ) ) {
		return new WP_Error( 'invalid_username', __( 'Sorry, that username is not allowed.' ) );
	}

	/*
	 * If a nicename is provided, remove unsafe user characters before using it.
	 * Otherwise build a nicename from the user_login.
	 */
	if ( ! empty( $userdata['user_nicename'] ) ) {
		$user_nicename = sanitize_user( $userdata['user_nicename'], true );
		if ( mb_strlen( $user_nicename ) > 50 ) {
			return new WP_Error( 'user_nicename_too_long', __( 'Nicename may not be longer than 50 characters.' ) );
		}
	} else {
		$user_nicename = mb_substr( $user_login, 0, 50 );
	}

	$user_nicename = sanitize_title( $user_nicename );

	/**
	 * Filters a user's nicename before the user is created or updated.
	 *
	 * @since 2.0.3
	 *
	 * @param string $user_nicename The user's nicename.
	 */
	$user_nicename = apply_filters( 'pre_user_nicename', $user_nicename );

	$user_nicename_check = $wpdb->get_var( $wpdb->prepare( "SELECT ID FROM $wpdb->users WHERE user_nicename = %s AND user_login != %s LIMIT 1", $user_nicename, $user_login ) );

	if ( $user_nicename_check ) {
		$suffix = 2;
		while ( $user_nicename_check ) {
			// user_nicename allows 50 chars. Subtract one for a hyphen, plus the length of the suffix.
			$base_length         = 49 - mb_strlen( $suffix );
			$alt_user_nicename   = mb_substr( $user_nicename, 0, $base_length ) . "-$suffix";
			$user_nicename_check = $wpdb->get_var( $wpdb->prepare( "SELECT ID FROM $wpdb->users WHERE user_nicename = %s AND user_login != %s LIMIT 1", $alt_user_nicename, $user_login ) );
			$suffix++;
		}
		$user_nicename = $alt_user_nicename;
	}

	$raw_user_email = empty( $userdata['user_email'] ) ? '' : $userdata['user_email'];

	/**
	 * Filters a user's email before the user is created or updated.
	 *
	 * @since 2.0.3
	 *
	 * @param string $raw_user_email The user's email.
	 */
	$user_email = apply_filters( 'pre_user_email', $raw_user_email );

	/*
	 * If there is no update, just check for `email_exists`. If there is an update,
	 * check if current email and new email are the same, and check `email_exists`
	 * accordingly.
	 */
	if ( ( ! $update || ( ! empty( $old_user_data ) && 0 !== strcasecmp( $user_email, $old_user_data->user_email ) ) )
		&& ! defined( 'WP_IMPORTING' )
		&& email_exists( $user_email )
	) {
		return new WP_Error( 'existing_user_email', __( 'Sorry, that email address is already used!' ) );
	}

	$raw_user_url = empty( $userdata['user_url'] ) ? '' : $userdata['user_url'];

	/**
	 * Filters a user's URL before the user is created or updated.
	 *
	 * @since 2.0.3
	 *
	 * @param string $raw_user_url The user's URL.
	 */
	$user_url = apply_filters( 'pre_user_url', $raw_user_url );

	$user_registered = empty( $userdata['user_registered'] ) ? gmdate( 'Y-m-d H:i:s' ) : $userdata['user_registered'];

	$user_activation_key = empty( $userdata['user_activation_key'] ) ? '' : $userdata['user_activation_key'];

	if ( ! empty( $userdata['spam'] ) && ! is_multisite() ) {
		return new WP_Error( 'no_spam', __( 'Sorry, marking a user as spam is only supported on Multisite.' ) );
	}

	$spam = empty( $userdata['spam'] ) ? 0 : (bool) $userdata['spam'];

	// Store values to save in user meta.
	$meta = array();

	$nickname = empty( $userdata['nickname'] ) ? $user_login : $userdata['nickname'];

	/**
	 * Filters a user's nickname before the user is created or updated.
	 *
	 * @since 2.0.3
	 *
	 * @param string $nickname The user's nickname.
	 */
	$meta['nickname'] = apply_filters( 'pre_user_nickname', $nickname );

	$first_name = empty( $userdata['first_name'] ) ? '' : $userdata['first_name'];

	/**
	 * Filters a user's first name before the user is created or updated.
	 *
	 * @since 2.0.3
	 *
	 * @param string $first_name The user's first name.
	 */
	$meta['first_name'] = apply_filters( 'pre_user_first_name', $first_name );

	$last_name = empty( $userdata['last_name'] ) ? '' : $userdata['last_name'];

	/**
	 * Filters a user's last name before the user is created or updated.
	 *
	 * @since 2.0.3
	 *
	 * @param string $last_name The user's last name.
	 */
	$meta['last_name'] = apply_filters( 'pre_user_last_name', $last_name );

	if ( empty( $userdata['display_name'] ) ) {
		if ( $update ) {
			$display_name = $user_login;
		} elseif ( $meta['first_name'] && $meta['last_name'] ) {
			/* translators: 1: User's first name, 2: Last name. */
			$display_name = sprintf( _x( '%1$s %2$s', 'Display name based on first name and last name' ), $meta['first_name'], $meta['last_name'] );
		} elseif ( $meta['first_name'] ) {
			$display_name = $meta['first_name'];
		} elseif ( $meta['last_name'] ) {
			$display_name = $meta['last_name'];
		} else {
			$display_name = $user_login;
		}
	} else {
		$display_name = $userdata['display_name'];
	}

	/**
	 * Filters a user's display name before the user is created or updated.
	 *
	 * @since 2.0.3
	 *
	 * @param string $display_name The user's display name.
	 */
	$display_name = apply_filters( 'pre_user_display_name', $display_name );

	$description = empty( $userdata['description'] ) ? '' : $userdata['description'];

	/**
	 * Filters a user's description before the user is created or updated.
	 *
	 * @since 2.0.3
	 *
	 * @param string $description The user's description.
	 */
	$meta['description'] = apply_filters( 'pre_user_description', $description );

	$meta['rich_editing'] = empty( $userdata['rich_editing'] ) ? 'true' : $userdata['rich_editing'];

	$meta['syntax_highlighting'] = empty( $userdata['syntax_highlighting'] ) ? 'true' : $userdata['syntax_highlighting'];

	$meta['comment_shortcuts'] = empty( $userdata['comment_shortcuts'] ) || 'false' === $userdata['comment_shortcuts'] ? 'false' : 'true';

	$admin_color         = empty( $userdata['admin_color'] ) ? 'fresh' : $userdata['admin_color'];
	$meta['admin_color'] = preg_replace( '|[^a-z0-9 _.\[email protected]]|i', '', $admin_color );

	$meta['use_ssl'] = empty( $userdata['use_ssl'] ) ? 0 : (bool) $userdata['use_ssl'];

	$meta['show_admin_bar_front'] = empty( $userdata['show_admin_bar_front'] ) ? 'true' : $userdata['show_admin_bar_front'];

	$meta['locale'] = isset( $userdata['locale'] ) ? $userdata['locale'] : '';

	$compacted = compact( 'user_pass', 'user_nicename', 'user_email', 'user_url', 'user_registered', 'user_activation_key', 'display_name' );
	$data      = wp_unslash( $compacted );

	if ( ! $update ) {
		$data = $data + compact( 'user_login' );
	}

	if ( is_multisite() ) {
		$data = $data + compact( 'spam' );
	}

	/**
	 * Filters user data before the record is created or updated.
	 *
	 * It only includes data in the users table, not any user metadata.
	 *
	 * @since 4.9.0
	 * @since 5.8.0 The `$userdata` parameter was added.
	 *
	 * @param array    $data {
	 *     Values and keys for the user.
	 *
	 *     @type string $user_login      The user's login. Only included if $update == false
	 *     @type string $user_pass       The user's password.
	 *     @type string $user_email      The user's email.
	 *     @type string $user_url        The user's url.
	 *     @type string $user_nicename   The user's nice name. Defaults to a URL-safe version of user's login
	 *     @type string $display_name    The user's display name.
	 *     @type string $user_registered MySQL timestamp describing the moment when the user registered. Defaults to
	 *                                   the current UTC timestamp.
	 * }
	 * @param bool     $update   Whether the user is being updated rather than created.
	 * @param int|null $user_id  ID of the user to be updated, or NULL if the user is being created.
	 * @param array    $userdata The raw array of data passed to wp_insert_user().
	 */
	$data = apply_filters( 'wp_pre_insert_user_data', $data, $update, ( $update ? $user_id : null ), $userdata );

	if ( empty( $data ) || ! is_array( $data ) ) {
		return new WP_Error( 'empty_data', __( 'Not enough data to create this user.' ) );
	}

	if ( $update ) {
		if ( $user_email !== $old_user_data->user_email || $user_pass !== $old_user_data->user_pass ) {
			$data['user_activation_key'] = '';
		}
		$wpdb->update( $wpdb->users, $data, array( 'ID' => $user_id ) );
	} else {
		$wpdb->insert( $wpdb->users, $data );
		$user_id = (int) $wpdb->insert_id;
	}

	$user = new WP_User( $user_id );

	/**
	 * Filters a user's meta values and keys immediately after the user is created or updated
	 * and before any user meta is inserted or updated.
	 *
	 * Does not include contact methods. These are added using `wp_get_user_contact_methods( $user )`.
	 *
	 * For custom meta fields, see the {@see 'insert_custom_user_meta'} filter.
	 *
	 * @since 4.4.0
	 * @since 5.8.0 The `$userdata` parameter was added.
	 *
	 * @param array $meta {
	 *     Default meta values and keys for the user.
	 *
	 *     @type string   $nickname             The user's nickname. Default is the user's username.
	 *     @type string   $first_name           The user's first name.
	 *     @type string   $last_name            The user's last name.
	 *     @type string   $description          The user's description.
	 *     @type string   $rich_editing         Whether to enable the rich-editor for the user. Default 'true'.
	 *     @type string   $syntax_highlighting  Whether to enable the rich code editor for the user. Default 'true'.
	 *     @type string   $comment_shortcuts    Whether to enable keyboard shortcuts for the user. Default 'false'.
	 *     @type string   $admin_color          The color scheme for a user's admin screen. Default 'fresh'.
	 *     @type int|bool $use_ssl              Whether to force SSL on the user's admin area. 0|false if SSL
	 *                                          is not forced.
	 *     @type string   $show_admin_bar_front Whether to show the admin bar on the front end for the user.
	 *                                          Default 'true'.
	 *     @type string   $locale               User's locale. Default empty.
	 * }
	 * @param WP_User $user     User object.
	 * @param bool    $update   Whether the user is being updated rather than created.
	 * @param array   $userdata The raw array of data passed to wp_insert_user().
	 */
	$meta = apply_filters( 'insert_user_meta', $meta, $user, $update, $userdata );

	$custom_meta = array();
	if ( array_key_exists( 'meta_input', $userdata ) && is_array( $userdata['meta_input'] ) && ! empty( $userdata['meta_input'] ) ) {
		$custom_meta = $userdata['meta_input'];
	}

	/**
	 * Filters a user's custom meta values and keys immediately after the user is created or updated
	 * and before any user meta is inserted or updated.
	 *
	 * For non-custom meta fields, see the {@see 'insert_user_meta'} filter.
	 *
	 * @since 5.9.0
	 *
	 * @param array   $custom_meta Array of custom user meta values keyed by meta key.
	 * @param WP_User $user        User object.
	 * @param bool    $update      Whether the user is being updated rather than created.
	 * @param array   $userdata    The raw array of data passed to wp_insert_user().
	 */
	$custom_meta = apply_filters( 'insert_custom_user_meta', $custom_meta, $user, $update, $userdata );

	$meta = array_merge( $meta, $custom_meta );

	// Update user meta.
	foreach ( $meta as $key => $value ) {
		update_user_meta( $user_id, $key, $value );
	}

	foreach ( wp_get_user_contact_methods( $user ) as $key => $value ) {
		if ( isset( $userdata[ $key ] ) ) {
			update_user_meta( $user_id, $key, $userdata[ $key ] );
		}
	}

	if ( isset( $userdata['role'] ) ) {
		$user->set_role( $userdata['role'] );
	} elseif ( ! $update ) {
		$user->set_role( get_option( 'default_role' ) );
	}

	clean_user_cache( $user_id );

	if ( $update ) {
		/**
		 * Fires immediately after an existing user is updated.
		 *
		 * @since 2.0.0
		 * @since 5.8.0 The `$userdata` parameter was added.
		 *
		 * @param int     $user_id       User ID.
		 * @param WP_User $old_user_data Object containing user's data prior to update.
		 * @param array   $userdata      The raw array of data passed to wp_insert_user().
		 */
		do_action( 'profile_update', $user_id, $old_user_data, $userdata );

		if ( isset( $userdata['spam'] ) && $userdata['spam'] != $old_user_data->spam ) {
			if ( 1 == $userdata['spam'] ) {
				/**
				 * Fires after the user is marked as a SPAM user.
				 *
				 * @since 3.0.0
				 *
				 * @param int $user_id ID of the user marked as SPAM.
				 */
				do_action( 'make_spam_user', $user_id );
			} else {
				/**
				 * Fires after the user is marked as a HAM user. Opposite of SPAM.
				 *
				 * @since 3.0.0
				 *
				 * @param int $user_id ID of the user marked as HAM.
				 */
				do_action( 'make_ham_user', $user_id );
			}
		}
	} else {
		/**
		 * Fires immediately after a new user is registered.
		 *
		 * @since 1.5.0
		 * @since 5.8.0 The `$userdata` parameter was added.
		 *
		 * @param int   $user_id  User ID.
		 * @param array $userdata The raw array of data passed to wp_insert_user().
		 */
		do_action( 'user_register', $user_id, $userdata );
	}

	return $user_id;
}