get_metadata() │ WP 2.9.0

Gets the metadata of the specified object (post, comment, user). Caches the result.

This is a fundamental metadata function. The parameter $meta_type here is responsible for binding to the database table, cache, hooks, and not to the post type or anything else. Therefore, for all post types, you need to specify post.

It is not recommended to use this function if you do not know exactly why you are using it. This function has all the necessary wrappers, and in 99% of cases, you should use them:

Uses: get_metadata_raw(), get_metadata_default(), update_meta_cache()
Used By: get_term_meta(), get_comment_meta(), get_user_meta(), get_post_meta()
1 time — 0.0005281 sec (slow) | 50000 times — 0.14 sec (very fast) | PHP 7.4.25, WP 6.0

No Hooks.

Returns

Mixed.

  • Will return false if $meta_type or $object_id are incorrectly passed (non-numeric, 0, or negative value).
  • When $single = true
    • string/array — when the meta-field exists.
    • '' — when the meta-field does not exist.
  • When $single = false
    • array of meta-field values — when the meta-field exists.
    • array() — when the meta-field does not exist.

If the value of the meta-field stores a number, it will be returned as a string, for example, "54"...

Usage

get_metadata( $meta_type, $object_id, $meta_key, $single );
$meta_type(string) (required)

The type of object whose metadata needs to be retrieved. Can be:

  • post - for all post types, table wp_postmeta.
  • term - for all taxonomy items, table wp_termmeta.
  • comment - for all comment types, table wp_commentmeta.
  • user - for users, table wp_usermeta.
  • custom_type - custom metadata table.
$object_id(number) (required)
ID of the object type specified in $meta_type, whose metadata needs to be retrieved. For example, here you write the post ID if the type is post.
$meta_key(string)
The name of the meta-field key. If this parameter is not specified, all values of all meta-fields of the object will be returned.
Default: ''
$single(boolean)

true — will return the meta-field value as a string or array (if the value of the meta-field contains a serialized array). If there are multiple meta-fields with the same key, the value of the first meta-field will be returned.

false — will return an array with the values of all meta-fields of the specified key. In this case, all values will be strings, even when the value contains a serialized array (you will need to manually convert it to an array).

If the value of a custom field contains a serialized array, then the value true will return a normal array, and if you specify false, it will return an array where the key "[0]" will contain the same serialized array.

This parameter works only if the parameter $key is specified!

Default: false

Examples

1

#1 Retrieve Post metadata

A few examples that can be used to output post, user and comment metadata. I.e. these are alternatives to corresponding WP functions: get_post_meta(), get_user_meta(), get_comment_meta().

// get the custom field of post 17, directly in the variable
$post_meta = get_metadata( 'post', 17, 'robots', true );

// Get the user's nickname 14
$user_meta = get_metadata( 'user', 14, 'nickname', 1 );

// Get all the metadata of comment 115, as an array.
$comment_meta = get_metadata( 'comment', 115 );
-19

#2 Example of returned array of all post metadatas

If we don't specify meta_key parameter, the function returns array of all meta-fields of post:

$metas = get_metadata( 'post', 115 );

// $metas will contain something like this:
array (
  '_pingme' => array (
	0 => '1',
  ),
  '_encloseme' => array (
	0 => '1',
  ),
  'custom key 1' => array (
	0 => 'custom value 1',
	1 => 'custom value 2',
  ),
  'custom key 2' => array (
	0 => 'custom value 3',
  ),
)

Notes

Changelog

Since 2.9.0 Introduced.

get_metadata() code WP 6.9

wp-includes/meta.php 
function get_metadata( $meta_type, $object_id, $meta_key = '', $single = false ) {
	$value = get_metadata_raw( $meta_type, $object_id, $meta_key, $single );
	if ( ! is_null( $value ) ) {
		return $value;
	}

	return get_metadata_default( $meta_type, $object_id, $meta_key, $single );
}

Metadatas (any)