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-fields with the same key, UNLESS a specific post in the table to be updated is specified.

Here’s how to do this when there are user meta-fields 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 for better illustration of the problem, 
// we want to change the title of `coffee_id` 12
$parameters = [
	'coffee_id' => '12',
	'title'     => 'A Delicious Cappuchino',
	'type'      => 'espresso',
];

// let's try to find the meta-fields ``favorite_coffee`` 
$previous_favorite_coffee = get_user_meta( $user_id, 'favorite_coffee', false );

/**
 * First, the condition when the user metadata favorite_coffee is absent
 */ 
if ( ! $previous_favorite_coffee ) {
	add_user_meta( $user_id, 'favorite_coffee', $parameters );
}

/**
 * Second, the condition when the user favorite_coffee already exists
 */
// recursive search through the posts returned by get_user_meta, 
// for the post you want to replace, as defined by `coffee_id`.
// See: http://php.net/manual/en/function.array-search.php#116635
$coffee_id = array_search( 
	$parameters['coffee_id'], 
	array_column( $previous_favorite_coffee, 'coffee_id' ) 
);

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