W3cubDocs

/WordPress

update_user_meta( int $user_id, string $meta_key, mixed $meta_value, mixed $prev_value = '' )

Update user meta field based on user ID.

Description

Use the $prev_value parameter to differentiate between meta fields with the same key and user ID.

If the meta field for the user does not exist, it will be added.

Parameters

$user_id

(int) (Required) User ID.

$meta_key

(string) (Required) Metadata key.

$meta_value

(mixed) (Required) Metadata value. Must be serializable if non-scalar.

$prev_value

(mixed) (Optional) Previous value to check before updating. If specified, only update existing metadata entries with this value. Otherwise, update all entries.

Default value: ''

Return

(int|bool) Meta ID if the key didn't exist, true on successful update, false on failure or if the value passed to the function is the same as the one that is already in the database.

More Information

Changes in behavior from the now deprecated update_usermeta:

Update_user_meta does not delete the meta if the new value is empty.

The actions are different.

Source

File: wp-includes/user.php 

function update_user_meta( $user_id, $meta_key, $meta_value, $prev_value = '' ) {
	return update_metadata( 'user', $user_id, $meta_key, $meta_value, $prev_value );
}

Uses

Uses Description
wp-includes/meta.php: update_metadata()

Updates metadata for the specified object. If no value already exists for the specified object ID and metadata key, the metadata will be added.

Used By

Used By Description
wp-includes/ms-site.php: wp_initialize_site()

Runs the initialization routine for a given site.
wp-admin/includes/class-wp-screen.php: WP_Screen::render_meta_boxes_preferences()

Render the meta boxes preferences.
wp-admin/includes/ajax-actions.php: wp_ajax_save_wporg_username()

Ajax handler for saving the user’s WordPress.org username.
wp-includes/class-wp-user-meta-session-tokens.php: WP_User_Meta_Session_Tokens::update_sessions()

Updates the user’s sessions in the usermeta table.
wp-admin/includes/ms.php: choose_primary_blog()

Handles the display of choosing a user’s primary site.
wp-includes/user.php: send_confirmation_on_profile_email()

Send a confirmation request email when a change of user email address is attempted.
wp-admin/includes/misc.php: set_screen_options()

Saves option for number of rows when listing posts, pages, comments, etc.
wp-admin/includes/schema.php: populate_network()

Populate network settings.
wp-admin/includes/upgrade.php: wp_install_defaults()

Creates the initial content for a newly-installed site.
wp-admin/includes/class-wp-plugin-install-list-table.php: WP_Plugin_Install_List_Table::prepare_items()
wp-admin/includes/ajax-actions.php: wp_ajax_save_user_color_scheme()

Ajax handler for auto-saving the selected color scheme for a user’s own profile.
wp-admin/includes/ajax-actions.php: wp_ajax_dismiss_wp_pointer()

Ajax handler for dismissing a WordPress pointer.
wp-admin/includes/ajax-actions.php: wp_ajax_update_welcome_panel()

Ajax handler for updating whether to display the welcome panel.
wp-includes/class-wp-user.php: WP_User::update_user_level_from_caps()

Update the maximum user level for the user.
wp-includes/class-wp-user.php: WP_User::add_cap()

Add capability and grant or deny access to capability.
wp-includes/class-wp-user.php: WP_User::remove_cap()

Remove capability from user.
wp-includes/class-wp-user.php: WP_User::add_role()

Add role to user.
wp-includes/class-wp-user.php: WP_User::remove_role()

Remove role from user.
wp-includes/class-wp-user.php: WP_User::set_role()

Set the role of the user.
wp-includes/user.php: wp_insert_user()

Insert a user into the database.
wp-includes/user.php: update_user_option()

Update user option with global blog capability.
wp-includes/ms-functions.php: add_new_user_to_blog()

Adds a newly created user to the appropriate blog
wp-includes/ms-functions.php: get_active_blog_for_user()

Get one of a user’s active blogs
wp-includes/ms-functions.php: add_user_to_blog()

Adds a user to a blog, along with specifying the user’s role.
wp-includes/ms-functions.php: remove_user_from_blog()

Remove a user from a blog.

Changelog

Version Description
3.0.0 Introduced.

© 2003–2019 WordPress Foundation
Licensed under the GNU GPLv2+ License.
https://developer.wordpress.org/reference/functions/update_user_meta