update_user_meta()WP 3.0.0

Update user meta field based on user ID.

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.

1 time — 0.000987 sec (slow) | 50000 times — 45.34 sec (very slow) | PHP 7.0.8, WP 4.6.1

No Hooks.

Return

Int|true|false. 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.

Usage

update_user_meta( $user_id, $meta_key, $meta_value, $prev_value );
$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)
Previous value to check before updating. If specified, only update existing metadata entries with this value. Otherwise, update all entries.
Default: ''

Examples

0

#1 Basic example

Suppose the user with ID 1 should have a meta field mood. Let's update its value or create a field if it doesn't exist.

update_user_meta( 1, 'mood', 'good' );
0

#2 Updating the user site

In the meta fields of the user we are familiar with: Nick, Name, Last Name, Site, etc. The example below shows how to update the site of the user with ID 1:

$user_id = 1;
$website = 'http://wordpress.org';
update_user_meta( $user_id, 'user_url', $website );
0

#3 Error check

This example shows how to check if the field has been updated:

$user_id = 1;
$new_value = 'good';

// It returns false if the previous value is equal to $new_value.
$updated = update_user_meta( $user_id, 'some_meta_key', $new_value );
if( ! $updated ){
	echo 'The field has not been updated';
}

// Get the value of the field and check it with the new value $new_value
$val = get_user_meta( $user_id,  'some_meta_key', true );
if( $val !== $new_value ){
	echo 'Error: no new value was written.';
}
0

#4 Note about update ALL user meta of the same key

update_user_meta() will update ALL user meta of the same key UNLESS you specify a specific record out of the set that you want to replace.

Here’s a way to do that, specifically for the instance where you have user meta that may look like this:

+---------+----------------------+-----------------
| user_id | meta_key             | meta_value 
+---------+----------------------+-----------------
| 862     | favorite_coffee      | {"coffee_id":10,"title":"Vietnamese Iced Coffee","type":"drip"}
| 862     | favorite_coffee      | {"coffee_id":11,"title":"Mocha","type":"espresso"}
| 862     | favorite_coffee      | {"coffee_id":12,"title":"Just An Okay Cappuchino","type":"espresso"}
// dummy data to better show the issue, we want to change the title of `coffee_id` 12
$parameters = array(
	'coffee_id' => '12',
	'title' => 'A Delicious Cappuchino',
	'type' => 'espresso',
);

// try to find some `favorite_coffee` user meta 
$previous_favorite_coffee = get_user_meta( $user_id, 'favorite_coffee', false );

/**
 * First, the condition for when no favorite_coffee user meta data exists
 */ 
if ( empty( $previous_favorite_coffee ) ) {
	add_user_meta( $user_id, 'favorite_coffee', $parameters );
}

/**
 * Second, the condition for when some favorite_coffee user_meta data already exists
 */
// search recursively through records returned from get_user_meta for the record you want to replace, as identified by `coffee_id` - credit: http://php.net/manual/en/function.array-search.php#116635
$coffee_id = array_search( $parameters['coffee_id'], array_column( $previous_favorite_coffee, 'coffee_id' ) );

if ( false === $coffee_id ) {
	// add if the wp_usermeta meta_key[favorite_coffee] => meta_value[ $parameters[ $coffee_id ] ] pair does not exist
	add_user_meta( $user_id, 'favorite_coffee', $parameters );
}
else {
	// update if the wp_usermeta meta_key[favorite_coffee] => meta_value[ $parameters[ $coffee_id ] ] pair already exists
	update_user_meta( $user_id, 'favorite_coffee', $parameters, $previous_favorite_coffee[ $coffee_id ] );
}

Changelog

Since 3.0.0 Introduced.

update_user_meta() code WP 6.5.2

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