update_user_meta() │ WP 3.0.0

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' );

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 );

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.';
}

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 ] );
}