update_user_meta( int $user_id, string $meta_key, mixed $meta_value, mixed $prev_value =  ): int|bool

Updates 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_idintrequired
User ID.
$meta_keystringrequired
Metadata key.
$meta_valuemixedrequired
Metadata value. Must be serializable if non-scalar.
$prev_valuemixedoptional
Previous value to check before updating.
If specified, only update existing metadata entries with this value. Otherwise, update all entries.

Default:''

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

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

Changelog

VersionDescription
3.0.0Introduced.

User Contributed Notes

  1. Skip to note 3 content

    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 ] );
    }
  2. Skip to note 4 content

    how to check for errors

    $user_id = 1;
    $new_value = 'some new value';
    
    // Will return false if the previous value is the same as $new_value.
    $updated = update_user_meta( $user_id, 'some_meta_key', $new_value );
    
    // So check and make sure the stored value matches $new_value.
    if ( $new_value != get_user_meta( $user_id,  'some_meta_key', true ) ) {
    	wp_die( __( 'An error occurred', 'textdomain' ) );
    }

You must log in before being able to contribute a note or feedback.