get_user_meta( int $user_id, string $key = '', bool $single = false ): mixed
- Since
- 3.0.0
- Source
wp-includes/user.php:1297
Compatibility
- WordPress
- since 3.0.0
- PHP
- 7.4–8.6-dev
- 6.7.7
- 6.8.8
- 6.9.7
- 7.0.4
- 7.1.0
Present in every tracked release (6.7.7 to 7.1.0), and compiles on PHP 7.4 through 8.6-dev.
Parameters
$user_idint- User ID.
$keystringoptional- The meta key to retrieve. By default, returns data for all keys.Default:
'' $singlebooloptional- Whether to return a single value.
This parameter has no effect if$keyis not specified.
Default false.Default:false
Return value
mixed- An array of values if
$singleis false.
The value of meta data field if$singleis true.
False for an invalid$user_id(non-numeric, zero, or negative value).
An empty array if a valid but non-existing user ID is passed and$singleis false.
An empty string if a valid but non-existing user ID is passed and$singleis true.
Note: Non-serialized values are returned as strings:
- false values are returned as empty strings ('')
- true values are returned as '1'
- numbers (both integer and float) are returned as strings Arrays and objects retain their original type.
Performance profile
How much work a call to get_user_meta() does, and what it touches: the algorithmic scaling, the Zend instruction count per call across PHP versions, the hooks it hands control to, and the core code that calls it. Measured from the compiled opcodes, not a stopwatch, so every number is identical on any machine running the same PHP version, and every function in core is ranked by cost.
- Cost class
- Trivial
- Scaling
- Constant
- Instructions
- 10
- Plugin surface
- None
- Called by
- 23
Touches nothing outside its own arguments.
No loop in the body: the same number of instructions runs whatever you pass in.
Executed per call on PHP 8.5. The body compiles to 10.
Nothing here hands control to plugin code.
23 places in core call this, so the cost is paid more often than your own code shows.
What one call costs · 1 distinct outcome
One number would be a lie: the work depends on which branch runs. These are every distinct cost get_user_meta() can have, taken from its control-flow graph on PHP 8.5.
| When | Instructions | Calls it makes |
|---|---|---|
| always | 10 | get_metadata() |
Across PHP versions
Compiles the same on PHP 7.4, 8.1, 8.2, 8.3, 8.4, 8.5 and 8.6-dev: 10 instructions, 10 executed per call, 0 branches. The work does not change between versions.
An instruction is not a fixed amount of time, so a matching count is not necessarily the same speed; what it rules out is a difference in the work itself.
Uses · 1
- get_metadata()Retrieves the value of a metadata field for the specified object type and ID.
Used by · 23
- WP_Application_Passwords::get_user_application_passwords()Gets a user's application passwords.
- WP_Internal_Pointers::enqueue_scripts()Initializes the new feature pointers.
- WP_Screen::render_meta_boxes_preferences()Renders the meta boxes preferences.
- WP_User::__get()Magic method for accessing custom fields.
- WP_User::get_caps_data()Gets the available user capabilities data.
- WP_User_Meta_Session_Tokens::get_sessions()Retrieves all sessions of the user.
- WP_Widget_Text::render_control_template_scripts()Renders form template scripts.
- add_user_to_blog()Adds a user to a blog, along with specifying the user's role.
- choose_primary_blog()Handles the display of choosing a user's primary site.
- get_active_blog_for_user()Gets one of a user's active blogs.
- get_blogs_of_user()Gets the sites a user belongs to.
- is_user_member_of_blog()Finds out whether a user is a member of a given blog.
Show all 23
- new_user_email_admin_notice()Adds an admin notice alerting the user to check for confirmation request email after email address change.
- register_and_do_post_meta_boxes()Registers the default post meta boxes, and runs the `do_meta_boxes` actions.
- remove_user_from_blog()Removes a user from a blog.
- the_block_editor_meta_boxes()Renders the meta boxes forms.
- upgrade_160()Execute changes made in WordPress 2.0.
- wp_ajax_dismiss_wp_pointer()Handles dismissing a WordPress pointer via AJAX.
- wp_ajax_save_user_color_scheme()Handles auto-saving the selected color scheme for a user's own profile via AJAX.
- wp_default_packages_inline_scripts()Adds inline scripts required for the WordPress JavaScript packages.
- wp_initialize_site()Runs the initialization routine for a given site.
- wp_update_user()Updates a user in the database.
- wp_user_personal_data_exporter()Finds and exports personal data associated with an email address from the user and user_meta table.
Source code
function get_user_meta( $user_id, $key = '', $single = false ) { return get_metadata( 'user', $user_id, $key, $single );}Changelog
Introduced in 3.0.0. Unchanged from 6.7.7 through 7.1.0.
Signature, return type and hooks compared across 5 parsed releases.
About this page
- Parsed data
- Generated from the wordpress-develop 7.1.0 tag, from
src/wp-includes/user.php, and regenerated for each WordPress release so it tracks the code rather than a snapshot of it. - Corrections
- Something wrong on this page? Report it and it gets fixed in the next regeneration.