get_user_meta( int $user_id, string $key = '', bool $single = false ): mixed
Retrieves user meta field for a user.
Contents
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
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.
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.
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 );
}
Changelog
Version | Description |
---|---|
3.0.0 | Introduced. |
User Contributed Notes
You must log in before being able to contribute a note or feedback.
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
Top ↑
Feedback
It will also return boolean
false
if! is_numeric( $user_id )
or! absint( $user_id )
. — By thenbrent —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
):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:
To avoid this, you may want to run a simple
array_map()
on the results ofget_user_meta()
in order to take only the first index of each result (thus emulating what the$single
argument does when$key
is provided: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 thearray_map()
above:This example returns and then displays the last name for user id 9.
Result:
The last_name value for user id 9 is Franklin
Note: When doing
get_user_meta( $user_id );
without a meta key, the values are not unserialized automatically. You will need tomaybe_unserialize()
them.To check if returned value is empty, ie does not exist, you could use something like:
Top ↑
Feedback
The function get_currentuserinfo() is deprecated: https://developer.wordpress.org/reference/functions/get_currentuserinfo/ — By Jacob Hill —