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

Description

Compatibility

Present in every tracked release (6.7.7 to 7.1.0), and compiles on PHP 7.4 through 8.6-dev.

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: 'modern'

  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 value

int|WP_Error

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

Performance profile

How much work a call to wp_insert_user() does, and what it touches: the algorithmic scaling, the Zend instruction count per call across PHP versions, the hooks it hands control to, and the core code that calls it. Measured from the compiled opcodes, not a stopwatch, so every number is identical on any machine running the same PHP version, and every function in core is ranked by cost.

Cost class

Heavy

Reaches the database via ->get_var().

Scaling

Scales with input

The body loops, so the work grows with what you pass in.

Instructions

271–355

Executed per call on PHP 8.5, depending on the branch taken. The body compiles to 714.

Plugin surface

18 hooks

Third-party callbacks on 'pre_user_login', 'illegal_user_logins', 'pre_user_nicename' run inside this call, and their cost is not bounded by anything here.

Called by

4

4 places in core call this, so the cost is paid more often than your own code shows.

What it touches

• hookthird-party callbacksapply_filters()called directly
• optionoption read or writeget_option()called directly
• sqldatabase query->get_var()called directly
• querycontent queryget_user_by()one call below wp_insert_user()
• cacheobject cachewp_cache_get()one call below wp_insert_user()
• serializeserialisationmaybe_unserialize()one call below wp_insert_user()

Further down the call graph this can also reach transient. That is the worst case, several calls deep and usually down an error path, not what a normal call pays.

What one call costs · 13 distinct outcomes

One number would be a lie: the work depends on which branch runs. These are every distinct cost wp_insert_user() can have, taken from its control-flow graph on PHP 8.5.

This body has more branch combinations than are worth enumerating, so the table covers the outcomes found first rather than every one that exists.

Hooks and filters fired · 18

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

1. 1
   apply_filters( pre_user_login )filterline 2313 (+92 into the body)

   Filters a username after it has been sanitized.

2. 2
   apply_filters( illegal_user_logins )filterline 2336 (+115 into the body)

   Filters the list of disallowed usernames.

3. 3
   apply_filters( pre_user_nicename )filterline 2361 (+140 into the body)

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

4. 4
   apply_filters( pre_user_email )filterline 2393 (+172 into the body)

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

5. 5
   apply_filters( pre_user_url )filterline 2416 (+195 into the body)

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

6. 6
   apply_filters( pre_user_nickname )filterline 2444 (+223 into the body)

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

7. 7
   apply_filters( pre_user_first_name )filterline 2455 (+234 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 2466 (+245 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 2496 (+275 into the body)

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

10. 10
    apply_filters( pre_user_description )filterline 2507 (+286 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 2562 (+341 into the body)

    Filters user data before the record is created or updated.

12. 12
    do_action( wp_set_password )actionline 2582 (+361 into the body)

    Fires after the user password is set.

13. 13
    apply_filters( insert_user_meta )filterline 2617 (+396 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.

14. 14
    apply_filters( insert_custom_user_meta )filterline 2637 (+416 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.

15. 15
    do_action( profile_update )actionline 2678 (+457 into the body)

    Fires immediately after an existing user is updated.

16. 16
    do_action( make_spam_user )actionline 2689 (+468 into the body)

    Fires after the user is marked as a SPAM user.

17. 17
    do_action( make_ham_user )actionline 2698 (+477 into the body)

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

18. 18
    do_action( user_register )actionline 2711 (+490 into the body)

    Fires immediately after a new user is registered.

Uses · 23

• 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_trigger_error()Generates a user-level error/warning/notice/deprecation message.
• 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.

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 code

View on Trac ↗View on GitHub ↗

2221function wp_insert_user( $userdata ) {2222	global $wpdb;2223 2224	if ( $userdata instanceof stdClass ) {2225		$userdata = get_object_vars( $userdata );2226	} elseif ( $userdata instanceof WP_User ) {2227		$userdata = $userdata->to_array();2228	} elseif ( $userdata instanceof Traversable ) {2229		$userdata = iterator_to_array( $userdata );2230	} elseif ( $userdata instanceof ArrayAccess ) {2231		$userdata_obj = $userdata;2232		$userdata     = array();2233		foreach (2234			array(2235				'ID',2236				'user_pass',2237				'user_login',2238				'user_nicename',2239				'user_url',2240				'user_email',2241				'display_name',2242				'nickname',2243				'first_name',2244				'last_name',2245				'description',2246				'rich_editing',2247				'syntax_highlighting',2248				'infinite_scrolling',2249				'comment_shortcuts',2250				'admin_color',2251				'use_ssl',2252				'user_registered',2253				'user_activation_key',2254				'spam',2255				'show_admin_bar_front',2256				'role',2257				'locale',2258				'meta_input',2259			) as $key2260		) {2261			if ( isset( $userdata_obj[ $key ] ) ) {2262				$userdata[ $key ] = $userdata_obj[ $key ];2263			}2264		}2265	} else {2266		$userdata = (array) $userdata;2267	}2268 2269	// Are we updating or creating?2270	if ( ! empty( $userdata['ID'] ) ) {2271		$user_id       = (int) $userdata['ID'];2272		$update        = true;2273		$old_user_data = get_userdata( $user_id );2274 2275		if ( ! $old_user_data ) {2276			return new WP_Error( 'invalid_user_id', __( 'Invalid user ID.' ) );2277		}2278 2279		// Slash current user email to compare it later with slashed new user email.2280		$old_user_data->user_email = wp_slash( $old_user_data->user_email );2281 2282		// Hashed in wp_update_user(), plaintext if called directly.2283		$user_pass = ! empty( $userdata['user_pass'] ) ? $userdata['user_pass'] : $old_user_data->user_pass;2284	} else {2285		$update = false;2286 2287		if ( empty( $userdata['user_pass'] ) ) {2288			wp_trigger_error(2289				__FUNCTION__,2290				__( 'The user_pass field is required when creating a new user. The user will need to reset their password before logging in.' ),2291				E_USER_WARNING2292			);2293 2294			// Set the password as an empty string to force the password reset flow.2295			$userdata['user_pass'] = '';2296		}2297 2298		// Hash the password.2299		$user_pass = wp_hash_password( $userdata['user_pass'] );2300	}

Changelog

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 7.1.0 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.