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

Update user meta field based on user ID.


Description 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.


Top ↑

Parameters 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: ''


Top ↑

Return 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.


Top ↑

More Information 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.


Top ↑

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


Top ↑

Changelog Changelog

Changelog
Version Description
3.0.0 Introduced.

Top ↑

User Contributed Notes User Contributed Notes

  1. Skip to note 1 content
    Contributed by Codex

    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' ) );
    }
    
  2. Skip to note 2 content
    Contributed by kimdcottrell

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

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