get_user_meta( int $user_id, string $key = '', bool $single = false ): mixed

Retrieves user meta field for a user.


Parameters

$user_id int Required
User ID.
$key string Optional
The meta key to retrieve. By default, returns data for all keys.

Default: ''

$single bool Optional
Whether to return a single value.
This parameter has no effect if $key is not specified.

Default: false


Top ↑

Return

mixed An array of values if $single is false.
The value of meta data field if $single is true.
False for an invalid $user_id (non-numeric, zero, or negative value).
An empty string if a valid but non-existing user ID is passed.


Top ↑

More Information

Please note that if the meta value exists but is empty, it will return an empty string (or array) as if the meta value didn’t exist. 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.


Top ↑

Source

File: wp-includes/user.php. View all references

function get_user_meta( $user_id, $key = '', $single = false ) {
	return get_metadata( 'user', $user_id, $key, $single );
}


Top ↑

Changelog

Changelog
Version Description
3.0.0 Introduced.

Top ↑

User Contributed Notes

  1. Skip to note 1 content
    Contributed by Giulio Daprela

    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

  2. Skip to note 2 content
    Contributed by Codex

    Getting all meta data
    This example demonstrates leaving the $key argument blank, in order to retrieve all meta data for the given user (in this example, user_id = 9):

    <?php
      $all_meta_for_user = get_user_meta( 9 );
      print_r( $all_meta_for_user );
    ?>

    Results:

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

    Note: In order to access the data in this example you need to dereference the array that is returned for each key, like so:

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

    To avoid this, you may want to run a simple array_map() on the results of get_user_meta() in order to take only the first index of each result (thus emulating what the $single argument does when $key is provided:

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

    Results:

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

    Additionally, if you want to return ALL meta for a specific user and filter out empty values, you can run array_filter() on the results of the array_map() above:

    // Get all user meta data for $user_id
    $meta = get_user_meta( $user_id );
    
    // Filter out empty meta data
    $meta = array_filter( array_map( function( $a ) {
    	return $a[0];
    }, $meta ) );
  3. Skip to note 3 content
    Contributed by Codex

    This example returns and then displays the last name for user id 9.

    <?php 
      $user_id = 9;
      $key = 'last_name';
      $single = true;
      $user_last = get_user_meta( $user_id, $key, $single ); 
      echo '<p>The '. $key . ' value for user id ' . $user_id . ' is: ' . $user_last . '</p>'; 
    ?>

    Result:

    The last_name value for user id 9 is Franklin

  4. Skip to note 4 content
    Contributed by Goran87

    To check if returned value is empty, ie does not exist, you could use something like:

    global $current_user; 
    
    get_currentuserinfo();
    
    if ( $current_user ) {
    	$permission = get_user_meta( $current_user->ID, 'some_meta' , true );
    	
    	if ( ! empty( $permission ) ) {
    		// do stuff
    	}
    }
    // works for both array and single values

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