wp_insert_user

Insert a user into the database.

Description

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

Most of the $userdata array fields have filters associated with the values. Exceptions are 'ID', rich_editing,, comment_shortcuts., admin_color, use_ssl, 'user_registered', and role. The filters have the prefix pre_user_ followed by the field name. An example using description would have the filter called, pre_user_description that can be hooked into.

Returns (int|WP_Error)

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

Parameters (1)

0. $userdata (array|object|WP_User)
An array, object, or WP_User object of user data arguments.

Options

  • ID (int) => 0

    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) => is the user's username

    The user's display name.

  • nickname (string) => is the user's username

    The user's nickname.

  • 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|bool) => ''

    Whether to enable the rich-editor for the user. False if not empty.

  • comment_shortcuts (string|bool) => false

    Whether to enable comment moderation keyboard shortcuts for the user.

  • admin_color (string) => 'fresh'

    Admin color scheme for the user.

  • use_ssl (bool) => false

    Whether the user should always access the admin over https.

  • user_registered (string) => ''

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

  • show_admin_bar_front (string|bool) => true

    Whether to display the Admin Bar for the user on the site's front end.

  • role (string) => ''

    User's role.

array(

    /**
     * User ID. If supplied, the user will be updated.
     *
     * @type int
     */
    'ID' => 0,

    /**
     * The plain-text user password.
     *
     * @type string
     * @default ''
     */
    'user_pass' => '',

    /**
     * The user's login username.
     *
     * @type string
     * @default ''
     */
    'user_login' => '',

    /**
     * The URL-friendly user name.
     *
     * @type string
     * @default ''
     */
    'user_nicename' => '',

    /**
     * The user URL.
     *
     * @type string
     * @default ''
     */
    'user_url' => '',

    /**
     * The user email address.
     *
     * @type string
     * @default ''
     */
    'user_email' => '',

    /**
     * The user's display name.
     *
     * @type string
     * @default is the user's username
     */
    'display_name' => is the user's username,

    /**
     * The user's nickname.
     *
     * @type string
     * @default is the user's username
     */
    'nickname' => is the user's username,

    /**
     * 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.
     *
     * @type string
     * @default ''
     */
    'first_name' => '',

    /**
     * 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.
     *
     * @type string
     * @default ''
     */
    'last_name' => '',

    /**
     * The user's biographical description.
     *
     * @type string
     * @default ''
     */
    'description' => '',

    /**
     * Whether to enable the rich-editor for the user. False if not empty.
     *
     * @type string|bool
     * @default ''
     */
    'rich_editing' => '',

    /**
     * Whether to enable comment moderation keyboard shortcuts for the user.
     *
     * @type string|bool
     * @default false
     */
    'comment_shortcuts' => false,

    /**
     * Admin color scheme for the user.
     *
     * @type string
     * @default 'fresh'
     */
    'admin_color' => 'fresh',

    /**
     * Whether the user should always access the admin over https.
     *
     * @type bool
     * @default false
     */
    'use_ssl' => false,

    /**
     * Date the user registered. Format is 'Y-m-d H:i:s'.
     *
     * @type string
     * @default ''
     */
    'user_registered' => '',

    /**
     * Whether to display the Admin Bar for the user on the site's front end.
     *
     * @type string|bool
     * @default true
     */
    'show_admin_bar_front' => true,

    /**
     * User's role.
     *
     * @type string
     * @default ''
     */
    'role' => ''
);        


Usage

  1. if ( !function_exists( 'wp_insert_user' ) ) { 
  2. require_once ABSPATH . WPINC . '/user.php'; 
  3.  
  4. // An array, object, or WP_User object of user data arguments. 
  5. $userdata = array( 
  6. 'ID' => 0, 
  7. 'user_pass' => '', 
  8. 'user_login' => '', 
  9. 'user_nicename' => '', 
  10. 'user_url' => '', 
  11. 'user_email' => '', 
  12. 'display_name' => is the user's username, 
  13. 'nickname' => is the user's username, 
  14. 'first_name' => '', 
  15. 'last_name' => '', 
  16. 'description' => '', 
  17. 'rich_editing' => '', 
  18. 'comment_shortcuts' => false, 
  19. 'admin_color' => 'fresh', 
  20. 'use_ssl' => false, 
  21. 'user_registered' => '', 
  22. 'show_admin_bar_front' => true, 
  23. 'role' => '' 
  24. ); 
  25.  
  26. // NOTICE! Understand what this does before running. 
  27. $result = wp_insert_user($userdata); 
  28.  

Defined (1)

The function is defined in the following location(s).

/wp-includes/user.php  
  1. function wp_insert_user( $userdata ) { 
  2. global $wpdb; 
  3.  
  4. if ( $userdata instanceof stdClass ) { 
  5. $userdata = get_object_vars( $userdata ); 
  6. } elseif ( $userdata instanceof WP_User ) { 
  7. $userdata = $userdata->to_array(); 
  8.  
  9. // Are we updating or creating? 
  10. if ( ! empty( $userdata['ID'] ) ) { 
  11. $ID = (int) $userdata['ID']; 
  12. $update = true; 
  13. $old_user_data = get_userdata( $ID ); 
  14.  
  15. if ( ! $old_user_data ) { 
  16. return new WP_Error( 'invalid_user_id', __( 'Invalid user ID.' ) ); 
  17.  
  18. // hashed in wp_update_user(), plaintext if called directly 
  19. $user_pass = ! empty( $userdata['user_pass'] ) ? $userdata['user_pass'] : $old_user_data->user_pass; 
  20. } else { 
  21. $update = false; 
  22. // Hash the password 
  23. $user_pass = wp_hash_password( $userdata['user_pass'] ); 
  24.  
  25. $sanitized_user_login = sanitize_user( $userdata['user_login'], true ); 
  26.  
  27. /** 
  28. * Filters a username after it has been sanitized. 
  29. * This filter is called before the user is created or updated. 
  30. * @since 2.0.3 
  31. * @param string $sanitized_user_login Username after it has been sanitized. 
  32. */ 
  33. $pre_user_login = apply_filters( 'pre_user_login', $sanitized_user_login ); 
  34.  
  35. //Remove any non-printable chars from the login string to see if we have ended up with an empty username 
  36. $user_login = trim( $pre_user_login ); 
  37.  
  38. // user_login must be between 0 and 60 characters. 
  39. if ( empty( $user_login ) ) { 
  40. return new WP_Error('empty_user_login', __('Cannot create a user with an empty login name.') ); 
  41. } elseif ( mb_strlen( $user_login ) > 60 ) { 
  42. return new WP_Error( 'user_login_too_long', __( 'Username may not be longer than 60 characters.' ) ); 
  43.  
  44. if ( ! $update && username_exists( $user_login ) ) { 
  45. return new WP_Error( 'existing_user_login', __( 'Sorry, that username already exists!' ) ); 
  46.  
  47. /** 
  48. * Filters the list of blacklisted usernames. 
  49. * @since 4.4.0 
  50. * @param array $usernames Array of blacklisted usernames. 
  51. */ 
  52. $illegal_logins = (array) apply_filters( 'illegal_user_logins', array() ); 
  53.  
  54. if ( in_array( strtolower( $user_login ), array_map( 'strtolower', $illegal_logins ) ) ) { 
  55. return new WP_Error( 'invalid_username', __( 'Sorry, that username is not allowed.' ) ); 
  56.  
  57. /** 
  58. * If a nicename is provided, remove unsafe user characters before using it. 
  59. * Otherwise build a nicename from the user_login. 
  60. */ 
  61. if ( ! empty( $userdata['user_nicename'] ) ) { 
  62. $user_nicename = sanitize_user( $userdata['user_nicename'], true ); 
  63. if ( mb_strlen( $user_nicename ) > 50 ) { 
  64. return new WP_Error( 'user_nicename_too_long', __( 'Nicename may not be longer than 50 characters.' ) ); 
  65. } else { 
  66. $user_nicename = mb_substr( $user_login, 0, 50 ); 
  67.  
  68. $user_nicename = sanitize_title( $user_nicename ); 
  69.  
  70. // Store values to save in user meta. 
  71. $meta = array(); 
  72.  
  73. /** 
  74. * Filters a user's nicename before the user is created or updated. 
  75. * @since 2.0.3 
  76. * @param string $user_nicename The user's nicename. 
  77. */ 
  78. $user_nicename = apply_filters( 'pre_user_nicename', $user_nicename ); 
  79.  
  80. $raw_user_url = empty( $userdata['user_url'] ) ? '' : $userdata['user_url']; 
  81.  
  82. /** 
  83. * Filters a user's URL before the user is created or updated. 
  84. * @since 2.0.3 
  85. * @param string $raw_user_url The user's URL. 
  86. */ 
  87. $user_url = apply_filters( 'pre_user_url', $raw_user_url ); 
  88.  
  89. $raw_user_email = empty( $userdata['user_email'] ) ? '' : $userdata['user_email']; 
  90.  
  91. /** 
  92. * Filters a user's email before the user is created or updated. 
  93. * @since 2.0.3 
  94. * @param string $raw_user_email The user's email. 
  95. */ 
  96. $user_email = apply_filters( 'pre_user_email', $raw_user_email ); 
  97.  
  98. /** 
  99. * If there is no update, just check for `email_exists`. If there is an update,  
  100. * check if current email and new email are the same, or not, and check `email_exists` 
  101. * accordingly. 
  102. */ 
  103. if ( ( ! $update || ( ! empty( $old_user_data ) && 0 !== strcasecmp( $user_email, $old_user_data->user_email ) ) ) 
  104. && ! defined( 'WP_IMPORTING' ) 
  105. && email_exists( $user_email ) 
  106. ) { 
  107. return new WP_Error( 'existing_user_email', __( 'Sorry, that email address is already used!' ) ); 
  108. $nickname = empty( $userdata['nickname'] ) ? $user_login : $userdata['nickname']; 
  109.  
  110. /** 
  111. * Filters a user's nickname before the user is created or updated. 
  112. * @since 2.0.3 
  113. * @param string $nickname The user's nickname. 
  114. */ 
  115. $meta['nickname'] = apply_filters( 'pre_user_nickname', $nickname ); 
  116.  
  117. $first_name = empty( $userdata['first_name'] ) ? '' : $userdata['first_name']; 
  118.  
  119. /** 
  120. * Filters a user's first name before the user is created or updated. 
  121. * @since 2.0.3 
  122. * @param string $first_name The user's first name. 
  123. */ 
  124. $meta['first_name'] = apply_filters( 'pre_user_first_name', $first_name ); 
  125.  
  126. $last_name = empty( $userdata['last_name'] ) ? '' : $userdata['last_name']; 
  127.  
  128. /** 
  129. * Filters a user's last name before the user is created or updated. 
  130. * @since 2.0.3 
  131. * @param string $last_name The user's last name. 
  132. */ 
  133. $meta['last_name'] = apply_filters( 'pre_user_last_name', $last_name ); 
  134.  
  135. if ( empty( $userdata['display_name'] ) ) { 
  136. if ( $update ) { 
  137. $display_name = $user_login; 
  138. } elseif ( $meta['first_name'] && $meta['last_name'] ) { 
  139. /** translators: 1: first name, 2: last name */ 
  140. $display_name = sprintf( _x( '%1$s %2$s', 'Display name based on first name and last name' ), $meta['first_name'], $meta['last_name'] ); 
  141. } elseif ( $meta['first_name'] ) { 
  142. $display_name = $meta['first_name']; 
  143. } elseif ( $meta['last_name'] ) { 
  144. $display_name = $meta['last_name']; 
  145. } else { 
  146. $display_name = $user_login; 
  147. } else { 
  148. $display_name = $userdata['display_name']; 
  149.  
  150. /** 
  151. * Filters a user's display name before the user is created or updated. 
  152. * @since 2.0.3 
  153. * @param string $display_name The user's display name. 
  154. */ 
  155. $display_name = apply_filters( 'pre_user_display_name', $display_name ); 
  156.  
  157. $description = empty( $userdata['description'] ) ? '' : $userdata['description']; 
  158.  
  159. /** 
  160. * Filters a user's description before the user is created or updated. 
  161. * @since 2.0.3 
  162. * @param string $description The user's description. 
  163. */ 
  164. $meta['description'] = apply_filters( 'pre_user_description', $description ); 
  165.  
  166. $meta['rich_editing'] = empty( $userdata['rich_editing'] ) ? 'true' : $userdata['rich_editing']; 
  167.  
  168. $meta['comment_shortcuts'] = empty( $userdata['comment_shortcuts'] ) || 'false' === $userdata['comment_shortcuts'] ? 'false' : 'true'; 
  169.  
  170. $admin_color = empty( $userdata['admin_color'] ) ? 'fresh' : $userdata['admin_color']; 
  171. $meta['admin_color'] = preg_replace( '|[^a-z0-9 _.\-@]|i', '', $admin_color ); 
  172.  
  173. $meta['use_ssl'] = empty( $userdata['use_ssl'] ) ? 0 : $userdata['use_ssl']; 
  174.  
  175. $user_registered = empty( $userdata['user_registered'] ) ? gmdate( 'Y-m-d H:i:s' ) : $userdata['user_registered']; 
  176.  
  177. $meta['show_admin_bar_front'] = empty( $userdata['show_admin_bar_front'] ) ? 'true' : $userdata['show_admin_bar_front']; 
  178.  
  179. $meta['locale'] = isset( $userdata['locale'] ) ? $userdata['locale'] : ''; 
  180.  
  181. $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)); 
  182.  
  183. if ( $user_nicename_check ) { 
  184. $suffix = 2; 
  185. while ($user_nicename_check) { 
  186. // user_nicename allows 50 chars. Subtract one for a hyphen, plus the length of the suffix. 
  187. $base_length = 49 - mb_strlen( $suffix ); 
  188. $alt_user_nicename = mb_substr( $user_nicename, 0, $base_length ) . "-$suffix"; 
  189. $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)); 
  190. $suffix++; 
  191. $user_nicename = $alt_user_nicename; 
  192.  
  193. $compacted = compact( 'user_pass', 'user_email', 'user_url', 'user_nicename', 'display_name', 'user_registered' ); 
  194. $data = wp_unslash( $compacted ); 
  195.  
  196. if ( $update ) { 
  197. if ( $user_email !== $old_user_data->user_email ) { 
  198. $data['user_activation_key'] = ''; 
  199. $wpdb->update( $wpdb->users, $data, compact( 'ID' ) ); 
  200. $user_id = (int) $ID; 
  201. } else { 
  202. $wpdb->insert( $wpdb->users, $data + compact( 'user_login' ) ); 
  203. $user_id = (int) $wpdb->insert_id; 
  204.  
  205. $user = new WP_User( $user_id ); 
  206.  
  207. /** 
  208. * Filters a user's meta values and keys before the user is created or updated. 
  209. * Does not include contact methods. These are added using `wp_get_user_contact_methods( $user )`. 
  210. * @since 4.4.0 
  211. * @param array $meta { 
  212. * Default meta values and keys for the user. 
  213. * @type string $nickname The user's nickname. Default is the user's username. 
  214. * @type string $first_name The user's first name. 
  215. * @type string $last_name The user's last name. 
  216. * @type string $description The user's description. 
  217. * @type bool $rich_editing Whether to enable the rich-editor for the user. False if not empty. 
  218. * @type bool $comment_shortcuts Whether to enable keyboard shortcuts for the user. Default false. 
  219. * @type string $admin_color The color scheme for a user's admin screen. Default 'fresh'. 
  220. * @type int|bool $use_ssl Whether to force SSL on the user's admin area. 0|false if SSL is 
  221. * not forced. 
  222. * @type bool $show_admin_bar_front Whether to show the admin bar on the front end for the user. 
  223. * Default true. 
  224. * } 
  225. * @param WP_User $user User object. 
  226. * @param bool $update Whether the user is being updated rather than created. 
  227. */ 
  228. $meta = apply_filters( 'insert_user_meta', $meta, $user, $update ); 
  229.  
  230. // Update user meta. 
  231. foreach ( $meta as $key => $value ) { 
  232. update_user_meta( $user_id, $key, $value ); 
  233.  
  234. foreach ( wp_get_user_contact_methods( $user ) as $key => $value ) { 
  235. if ( isset( $userdata[ $key ] ) ) { 
  236. update_user_meta( $user_id, $key, $userdata[ $key ] ); 
  237.  
  238. if ( isset( $userdata['role'] ) ) { 
  239. $user->set_role( $userdata['role'] ); 
  240. } elseif ( ! $update ) { 
  241. $user->set_role(get_option('default_role')); 
  242. wp_cache_delete( $user_id, 'users' ); 
  243. wp_cache_delete( $user_login, 'userlogins' ); 
  244.  
  245. if ( $update ) { 
  246. /** 
  247. * Fires immediately after an existing user is updated. 
  248. * @since 2.0.0 
  249. * @param int $user_id User ID. 
  250. * @param object $old_user_data Object containing user's data prior to update. 
  251. */ 
  252. do_action( 'profile_update', $user_id, $old_user_data ); 
  253. } else { 
  254. /** 
  255. * Fires immediately after a new user is registered. 
  256. * @since 1.5.0 
  257. * @param int $user_id User ID. 
  258. */ 
  259. do_action( 'user_register', $user_id ); 
  260.  
  261. return $user_id;