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.

$prev_value

(mixed) (Optional) Previous value to check before removing.

Default value: ''


Top ↑

Return Return

(int|bool) Meta ID if the key didn't exist, true on successful update, false on failure.


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.