wp_insert_user( array|object|WP_User $userdata ): int|WP_Error

Description

Parameters

$userdataarray|object|WP_User

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

• $IDint

  User ID. If supplied, the user will be updated.

• $user_passstring

  The plain-text user password for new users. Hashed password for existing users.

• $user_loginstring

  The user's login username.

• $user_nicenamestring

  The URL-friendly user name.

• $user_urlstring

  The user URL.

• $user_emailstring

  The user email address.

• $display_namestringdefault: is the user's username

  The user's display name.

• $nicknamestringdefault: is the user's username

  The user's nickname.

• $first_namestring

  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_namestring

  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.

• $descriptionstring

  The user's biographical description.

• $rich_editingstringdefault: 'true'

  Whether to enable the rich-editor for the user. Accepts 'true' or 'false' as a string literal, not boolean.

• $syntax_highlightingstringdefault: 'true'

  Whether to enable the rich code editor for the user. Accepts 'true' or 'false' as a string literal, not boolean.

• $comment_shortcutsstringdefault: 'false'

  Whether to enable comment moderation keyboard shortcuts for the user. Accepts 'true' or 'false' as a string literal, not boolean.

• $admin_colorstringdefault: 'fresh'

  Admin color scheme for the user.

• $use_sslbooldefault: false

  Whether the user should always access the admin over https.

• $user_registeredstring

  Date the user registered in UTC. Format is 'Y-m-d H:i:s'.

• $user_activation_keystringdefault: empty

  Password reset key.

• $spambooldefault: false

  Multisite only. Whether the user is marked as spam.

• $show_admin_bar_frontstringdefault: 'true'

  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.

• $rolestring

  User's role.

• $localestringdefault: empty

  User's locale.

• $meta_inputarraydefault: empty

  Array of custom user meta values keyed by meta key.

Return

int|WP_Error

The newly created user's ID or a WP_Error object if the user could not be created.

Hooks fired · 17

17 hooks fire while wp_insert_user() runs, in this order:

1. 1
   apply_filters( pre_user_login )filterline 2167 (+41 into the body)

   Filters a username after it has been sanitized.

2. 2
   apply_filters( illegal_user_logins )filterline 2190 (+64 into the body)

   Filters the list of disallowed usernames.

3. 3
   apply_filters( pre_user_nicename )filterline 2215 (+89 into the body)

   Filters a user's nicename before the user is created or updated.

4. 4
   apply_filters( pre_user_email )filterline 2244 (+118 into the body)

   Filters a user's email before the user is created or updated.

5. 5
   apply_filters( pre_user_url )filterline 2267 (+141 into the body)

   Filters a user's URL before the user is created or updated.

6. 6
   apply_filters( pre_user_nickname )filterline 2295 (+169 into the body)

   Filters a user's nickname before the user is created or updated.

7. 7
   apply_filters( pre_user_first_name )filterline 2306 (+180 into the body)

   Filters a user's first name before the user is created or updated.

8. 8
   apply_filters( pre_user_last_name )filterline 2317 (+191 into the body)

   Filters a user's last name before the user is created or updated.

9. 9
   apply_filters( pre_user_display_name )filterline 2347 (+221 into the body)

   Filters a user's display name before the user is created or updated.

10. 10
    apply_filters( pre_user_description )filterline 2358 (+232 into the body)

    Filters a user's description before the user is created or updated.

11. 11
    apply_filters( wp_pre_insert_user_data )filterline 2410 (+284 into the body)

    Filters user data before the record is created or updated.

12. 12
    apply_filters( insert_user_meta )filterline 2460 (+334 into the body)

    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.

13. 13
    apply_filters( insert_custom_user_meta )filterline 2480 (+354 into the body)

    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.

14. 14
    do_action( profile_update )actionline 2521 (+395 into the body)

    Fires immediately after an existing user is updated.

15. 15
    do_action( make_spam_user )actionline 2532 (+406 into the body)

    Fires after the user is marked as a SPAM user.

16. 16
    do_action( make_ham_user )actionline 2541 (+415 into the body)

    Fires after the user is marked as a HAM user. Opposite of SPAM.

17. 17
    do_action( user_register )actionline 2554 (+428 into the body)

    Fires immediately after a new user is registered.

Uses · 22

• get_userdata()Retrieves user info by user ID.
• __()Retrieves the translation of $text.
• wp_slash()Adds slashes to a string or recursively adds slashes to strings within an array.
• wp_hash_password()Creates a hash of a plain text password.
• sanitize_user()Sanitizes a username, stripping out unsafe characters.
• apply_filters()Calls the callback functions that have been added to a filter hook.
• mb_strlen()Compat function to mimic mb_strlen().
• username_exists()Determines whether the given username exists.
• mb_substr()Compat function to mimic mb_substr().
• sanitize_title()Sanitizes a string into a slug, which can be used in URLs or HTML attributes.
• email_exists()Determines whether the given email exists.
• is_multisite()Determines whether Multisite is enabled.

Used by · 4

• WP_REST_Users_Controller::create_item()Creates a single user.
• edit_user()Edit user settings based on contents of $_POST
• wp_create_user()Provides a simpler way of inserting a user into the database.
• wp_update_user()Updates a user in the database.

Source

View on Trac ↗View on GitHub ↗

2126function wp_insert_user( $userdata ) {2127	global $wpdb;2128 2129	if ( $userdata instanceof stdClass ) {2130		$userdata = get_object_vars( $userdata );2131	} elseif ( $userdata instanceof WP_User ) {2132		$userdata = $userdata->to_array();2133	}2134 2135	// Are we updating or creating?2136	if ( ! empty( $userdata['ID'] ) ) {2137		$user_id       = (int) $userdata['ID'];2138		$update        = true;2139		$old_user_data = get_userdata( $user_id );2140 2141		if ( ! $old_user_data ) {2142			return new WP_Error( 'invalid_user_id', __( 'Invalid user ID.' ) );2143		}2144 2145		// Slash current user email to compare it later with slashed new user email.2146		$old_user_data->user_email = wp_slash( $old_user_data->user_email );2147 2148		// Hashed in wp_update_user(), plaintext if called directly.2149		$user_pass = ! empty( $userdata['user_pass'] ) ? $userdata['user_pass'] : $old_user_data->user_pass;2150	} else {2151		$update = false;2152		// Hash the password.2153		$user_pass = wp_hash_password( $userdata['user_pass'] );2154	}2155 2156	$sanitized_user_login = sanitize_user( $userdata['user_login'], true );2157 2158	/**2159	 * Filters a username after it has been sanitized.2160	 *2161	 * This filter is called before the user is created or updated.2162	 *2163	 * @since 2.0.32164	 *2165	 * @param string $sanitized_user_login Username after it has been sanitized.2166	 */2167	$pre_user_login = apply_filters( 'pre_user_login', $sanitized_user_login );2168 2169	// Remove any non-printable chars from the login string to see if we have ended up with an empty username.2170	$user_login = trim( $pre_user_login );2171 2172	// user_login must be between 0 and 60 characters.2173	if ( empty( $user_login ) ) {2174		return new WP_Error( 'empty_user_login', __( 'Cannot create a user with an empty login name.' ) );2175	} elseif ( mb_strlen( $user_login ) > 60 ) {2176		return new WP_Error( 'user_login_too_long', __( 'Username may not be longer than 60 characters.' ) );2177	}2178 2179	if ( ! $update && username_exists( $user_login ) ) {2180		return new WP_Error( 'existing_user_login', __( 'Sorry, that username already exists!' ) );2181	}2182 2183	/**2184	 * Filters the list of disallowed usernames.2185	 *2186	 * @since 4.4.02187	 *2188	 * @param array $usernames Array of disallowed usernames.2189	 */2190	$illegal_logins = (array) apply_filters( 'illegal_user_logins', array() );2191 2192	if ( in_array( strtolower( $user_login ), array_map( 'strtolower', $illegal_logins ), true ) ) {2193		return new WP_Error( 'invalid_username', __( 'Sorry, that username is not allowed.' ) );2194	}2195 2196	/*2197	 * If a nicename is provided, remove unsafe user characters before using it.2198	 * Otherwise build a nicename from the user_login.2199	 */2200	if ( ! empty( $userdata['user_nicename'] ) ) {2201		$user_nicename = sanitize_user( $userdata['user_nicename'], true );2202	} else {2203		$user_nicename = mb_substr( $user_login, 0, 50 );2204	}2205

History

Introduced in 2.0.0. Unchanged from 6.7.7 through 7.1.0.

1. 6.7.7
2. 6.8.8
3. 6.9.7
4. 7.0.4
5. 7.1.0

Signature, return type and hooks compared across 5 parsed releases.

About this page

Parsed data

Generated from the wordpress-develop 6.7.7 tag, from src/wp-includes/user.php, and regenerated for each WordPress release so it tracks the code rather than a snapshot of it.

Corrections

Something wrong on this page? Report it and it gets fixed in the next regeneration.