get_user_meta() │ WP 3.0.0

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

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

#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

#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.
)
*/

#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
}