get_user_meta() │ WP 3.0.0

Gets an single meta field or all meta fields of the specified user.

If the key does not exist the function will return an empty string or an empty array depending on the value of the $single parameter.

This might cause unexpected behaviors in your code when you empty the user meta, your code can try to use add_user_meta instead of update_user_meta thinking the user does not have meta created yet.

Note: When doing get_user_meta( $user_id ); without a meta key, the values are not unserialized automatically. You will need to maybe_unserialize() them.

User meta fields are the same as the custom fields for posts, only here the post is the user and the custom field is the user's meta field. Meta fields are stored in the wp_usermeta table, which is the same as the wp_postmeta table for posts.

Uses: get_metadata()
1 time — 0.000998 sec (slow) | 50000 times — 0.09 sec (speed of light) | PHP 7.1.2, WP 4.7.5

No Hooks.

Return

Mixed.

  • Returns false when $user_id parameter passed wrongly.

  • If $single = true

    • string/array — when metafield exists.
    • '' — when metafield not exists.
  • If $single = false
    • array of all metafield values — when metafield exists.
    • array() — when metafield not exists.

If a number is stored it will be returned as a numeric string, for example, '54'.

Usage

get_user_meta( $user_id, $key, $single );
$user_id(int) (required)
User ID.
$key(string)
The meta key to retrieve. By default, returns data for all keys.
Default: ''
$single(true|false)
Whether to return a single value. This parameter has no effect if $key is not specified.
Default: false

Examples

0

#1 Usage Example

This example will retrieve and then display the user's nickname with ID = 9:

$user_id = 9;
$key = 'nickname';
$meta_val = get_user_meta( $user_id, $key, true );

echo sprintf( 'The value of the %s key of user %d is: %s', $key, $user_id, $meta_val );

// display:
// The value of the nickname key of user 9 is: Enot
0

#2 Get all metadata

This example shows what happens if $key is left blank to get all metadata of a specified user:

$all_meta_for_user = get_user_meta( 9 );

/*
$all_meta_for_user will contain array:
Array (
	[first_name] => Array ( [0] => Tom )
	[last_name] => Array ( [0] => Auger)
	[nickname] => Array ( [0] => tomauger )
	[description] => etc...
)
*/

To get the data from this example, you need to get the first element of the array, so:

$last_name = $all_meta_for_user['last_name'][0];

To avoid this inconvenience, it may be better to apply your function to the resulting array using array_map():

$all_meta_for_user = array_map(
	function( $a ){
		return $a[0];
	},
	get_user_meta( $user_id )
);

/*
Now, $all_meta_for_user will contain such an array:

Array (
	[first_name] => Tom
	[last_name] => Auger
	[nickname] => tomauger
	[description] => etc.
)
*/
0

#3 Check that the meta field exists 

// for single value
$value = get_post_meta( 76, 'key_1', true );

if( '' !== $value ){
	// the meta-field is
}

// for multiple values
$value = get_post_meta( 76, 'key_1' );

if( [] !== $value ){
	// meta field is
}

Changelog

Since 3.0.0 Introduced.

get_user_meta() code WP 6.1.1

wp-includes/user.php 
function get_user_meta( $user_id, $key = '', $single = false ) {
	return get_metadata( 'user', $user_id, $key, $single );
}

Metadatas (any)