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.


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 ↑

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

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