wp_update_user

Update a user in the database.

Description

(int|WP_Error) wp_update_user( (mixed) $userdata ); 

It is possible to update a user's password by specifying the user_pass value in the $userdata parameter array.

If current user's password is being updated, then the cookies will be cleared.

Returns (int|WP_Error)

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

Parameters (1)

0. $userdata (mixed)
An array of user data or a user object of type stdClass or WP_User.

Usage

  1. if ( !function_exists( 'wp_update_user' ) ) { 
  2. require_once ABSPATH . WPINC . '/user.php'; 
  3.  
  4. // An array of user data or a user object of type stdClass or WP_User. 
  5. $userdata = null; 
  6.  
  7. // NOTICE! Understand what this does before running. 
  8. $result = wp_update_user($userdata); 
  9.  

Defined (1)

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

/wp-includes/user.php  
  1. function wp_update_user($userdata) { 
  2. if ( $userdata instanceof stdClass ) { 
  3. $userdata = get_object_vars( $userdata ); 
  4. } elseif ( $userdata instanceof WP_User ) { 
  5. $userdata = $userdata->to_array(); 
  6.  
  7. $ID = isset( $userdata['ID'] ) ? (int) $userdata['ID'] : 0; 
  8. if ( ! $ID ) { 
  9. return new WP_Error( 'invalid_user_id', __( 'Invalid user ID.' ) ); 
  10.  
  11. // First, get all of the original fields 
  12. $user_obj = get_userdata( $ID ); 
  13. if ( ! $user_obj ) { 
  14. return new WP_Error( 'invalid_user_id', __( 'Invalid user ID.' ) ); 
  15.  
  16. $user = $user_obj->to_array(); 
  17.  
  18. // Add additional custom fields 
  19. foreach ( _get_additional_user_keys( $user_obj ) as $key ) { 
  20. $user[ $key ] = get_user_meta( $ID, $key, true ); 
  21.  
  22. // Escape data pulled from DB. 
  23. $user = add_magic_quotes( $user ); 
  24.  
  25. if ( ! empty( $userdata['user_pass'] ) && $userdata['user_pass'] !== $user_obj->user_pass ) { 
  26. // If password is changing, hash it now 
  27. $plaintext_pass = $userdata['user_pass']; 
  28. $userdata['user_pass'] = wp_hash_password( $userdata['user_pass'] ); 
  29.  
  30. /** 
  31. * Filters whether to send the password change email. 
  32. * @since 4.3.0 
  33. * @see wp_insert_user() For `$user` and `$userdata` fields. 
  34. * @param bool $send Whether to send the email. 
  35. * @param array $user The original user array. 
  36. * @param array $userdata The updated user array. 
  37. */ 
  38. $send_password_change_email = apply_filters( 'send_password_change_email', true, $user, $userdata ); 
  39.  
  40. if ( isset( $userdata['user_email'] ) && $user['user_email'] !== $userdata['user_email'] ) { 
  41. /** 
  42. * Filters whether to send the email change email. 
  43. * @since 4.3.0 
  44. * @see wp_insert_user() For `$user` and `$userdata` fields. 
  45. * @param bool $send Whether to send the email. 
  46. * @param array $user The original user array. 
  47. * @param array $userdata The updated user array. 
  48. */ 
  49. $send_email_change_email = apply_filters( 'send_email_change_email', true, $user, $userdata ); 
  50.  
  51. wp_cache_delete( $user['user_email'], 'useremail' ); 
  52. wp_cache_delete( $user['user_nicename'], 'userslugs' ); 
  53.  
  54. // Merge old and new fields with new fields overwriting old ones. 
  55. $userdata = array_merge( $user, $userdata ); 
  56. $user_id = wp_insert_user( $userdata ); 
  57.  
  58. if ( ! is_wp_error( $user_id ) ) { 
  59.  
  60. $blog_name = wp_specialchars_decode( get_option( 'blogname' ), ENT_QUOTES ); 
  61.  
  62. $switched_locale = false; 
  63. if ( ! empty( $send_password_change_email ) || ! empty( $send_email_change_email ) ) { 
  64. $switched_locale = switch_to_locale( get_user_locale( $user_id ) ); 
  65.  
  66. if ( ! empty( $send_password_change_email ) ) { 
  67. /** translators: Do not translate USERNAME, ADMIN_EMAIL, EMAIL, SITENAME, SITEURL: those are placeholders. */ 
  68. $pass_change_text = __( 'Hi ###USERNAME###,  
  69.  
  70. This notice confirms that your password was changed on ###SITENAME###. 
  71.  
  72. If you did not change your password, please contact the Site Administrator at 
  73. ###ADMIN_EMAIL### 
  74.  
  75. This email has been sent to ###EMAIL### 
  76.  
  77. Regards,  
  78. All at ###SITENAME### 
  79. ###SITEURL###' ); 
  80.  
  81. $pass_change_email = array( 
  82. 'to' => $user['user_email'],  
  83. /** translators: User password change notification email subject. 1: Site name */ 
  84. 'subject' => __( '[%s] Notice of Password Change' ),  
  85. 'message' => $pass_change_text,  
  86. 'headers' => '',  
  87. ); 
  88.  
  89. /** 
  90. * Filters the contents of the email sent when the user's password is changed. 
  91. * @since 4.3.0 
  92. * @param array $pass_change_email { 
  93. * Used to build wp_mail(). 
  94. * @type string $to The intended recipients. Add emails in a comma separated string. 
  95. * @type string $subject The subject of the email. 
  96. * @type string $message The content of the email. 
  97. * The following strings have a special meaning and will get replaced dynamically: 
  98. * - ###USERNAME### The current user's username. 
  99. * - ###ADMIN_EMAIL### The admin email in case this was unexpected. 
  100. * - ###EMAIL### The old email. 
  101. * - ###SITENAME### The name of the site. 
  102. * - ###SITEURL### The URL to the site. 
  103. * @type string $headers Headers. Add headers in a newline (\r\n) separated string. 
  104. * } 
  105. * @param array $user The original user array. 
  106. * @param array $userdata The updated user array. 
  107. */ 
  108. $pass_change_email = apply_filters( 'password_change_email', $pass_change_email, $user, $userdata ); 
  109.  
  110. $pass_change_email['message'] = str_replace( '###USERNAME###', $user['user_login'], $pass_change_email['message'] ); 
  111. $pass_change_email['message'] = str_replace( '###ADMIN_EMAIL###', get_option( 'admin_email' ), $pass_change_email['message'] ); 
  112. $pass_change_email['message'] = str_replace( '###EMAIL###', $user['user_email'], $pass_change_email['message'] ); 
  113. $pass_change_email['message'] = str_replace( '###SITENAME###', $blog_name, $pass_change_email['message'] ); 
  114. $pass_change_email['message'] = str_replace( '###SITEURL###', home_url(), $pass_change_email['message'] ); 
  115.  
  116. wp_mail( $pass_change_email['to'], sprintf( $pass_change_email['subject'], $blog_name ), $pass_change_email['message'], $pass_change_email['headers'] ); 
  117.  
  118. if ( ! empty( $send_email_change_email ) ) { 
  119. /** translators: Do not translate USERNAME, ADMIN_EMAIL, EMAIL, SITENAME, SITEURL: those are placeholders. */ 
  120. $email_change_text = __( 'Hi ###USERNAME###,  
  121.  
  122. This notice confirms that your email was changed on ###SITENAME###. 
  123.  
  124. If you did not change your email, please contact the Site Administrator at 
  125. ###ADMIN_EMAIL### 
  126.  
  127. This email has been sent to ###EMAIL### 
  128.  
  129. Regards,  
  130. All at ###SITENAME### 
  131. ###SITEURL###' ); 
  132.  
  133. $email_change_email = array( 
  134. 'to' => $user['user_email'],  
  135. /** translators: User email change notification email subject. 1: Site name */ 
  136. 'subject' => __( '[%s] Notice of Email Change' ),  
  137. 'message' => $email_change_text,  
  138. 'headers' => '',  
  139. ); 
  140.  
  141. /** 
  142. * Filters the contents of the email sent when the user's email is changed. 
  143. * @since 4.3.0 
  144. * @param array $email_change_email { 
  145. * Used to build wp_mail(). 
  146. * @type string $to The intended recipients. 
  147. * @type string $subject The subject of the email. 
  148. * @type string $message The content of the email. 
  149. * The following strings have a special meaning and will get replaced dynamically: 
  150. * - ###USERNAME### The current user's username. 
  151. * - ###ADMIN_EMAIL### The admin email in case this was unexpected. 
  152. * - ###EMAIL### The old email. 
  153. * - ###SITENAME### The name of the site. 
  154. * - ###SITEURL### The URL to the site. 
  155. * @type string $headers Headers. 
  156. * } 
  157. * @param array $user The original user array. 
  158. * @param array $userdata The updated user array. 
  159. */ 
  160. $email_change_email = apply_filters( 'email_change_email', $email_change_email, $user, $userdata ); 
  161.  
  162. $email_change_email['message'] = str_replace( '###USERNAME###', $user['user_login'], $email_change_email['message'] ); 
  163. $email_change_email['message'] = str_replace( '###ADMIN_EMAIL###', get_option( 'admin_email' ), $email_change_email['message'] ); 
  164. $email_change_email['message'] = str_replace( '###EMAIL###', $user['user_email'], $email_change_email['message'] ); 
  165. $email_change_email['message'] = str_replace( '###SITENAME###', $blog_name, $email_change_email['message'] ); 
  166. $email_change_email['message'] = str_replace( '###SITEURL###', home_url(), $email_change_email['message'] ); 
  167.  
  168. wp_mail( $email_change_email['to'], sprintf( $email_change_email['subject'], $blog_name ), $email_change_email['message'], $email_change_email['headers'] ); 
  169.  
  170. if ( $switched_locale ) { 
  171.  
  172. // Update the cookies if the password changed. 
  173. $current_user = wp_get_current_user(); 
  174. if ( $current_user->ID == $ID ) { 
  175. if ( isset($plaintext_pass) ) { 
  176.  
  177. // Here we calculate the expiration length of the current auth cookie and compare it to the default expiration. 
  178. // If it's greater than this, then we know the user checked 'Remember Me' when they logged in. 
  179. $logged_in_cookie = wp_parse_auth_cookie( '', 'logged_in' ); 
  180. /** This filter is documented in wp-includes/pluggable.php */ 
  181. $default_cookie_life = apply_filters( 'auth_cookie_expiration', ( 2 * DAY_IN_SECONDS ), $ID, false ); 
  182. $remember = ( ( $logged_in_cookie['expiration'] - time() ) > $default_cookie_life ); 
  183.  
  184. wp_set_auth_cookie( $ID, $remember ); 
  185.  
  186. return $user_id;