get_post_meta()
Gets the value of the specified custom field of the post. Also can get an array of all post meta fields.
In order to obtain the values of all custom fields of a particular post, you need to leave empty the $key parameter. You can also use the get_post_custom() function to do this.
If the metadata contains a serialized array, it will be automatically processed by unserialize() function. So, to get unserialized data you do not need to use unserialize() function on received data.
No Hooks.
Return
Mixed
.
-
Returns
false
when $post_id parameter passed wrongly. -
If $single = true
string/array
— when meta-field exists.''
— when the meta-field not exists.
- If $single = false
array of all metafield values
— when metafield exists.array()
— when metafield not exists.
Note: If a number is stored in meta-field it will be returned as a string, for example, '54'
...
Usage
get_post_meta( $post_id, $key, $single );
- $post_id(int) (required)
- Post ID whose custom field needs to be obtained.
- $key(string)
- The meta field name, the value you need to get. If leave the field empty, all post custom fields will be obtained.
Default: '' - $single(true/false)
Whether to return a single value.
true
- return the single value of meta-field (if there are several values with this key, then only the first one will be returned).
false
- return an array of all meta field values with the specified meta key.If the value of a custom field contains a serialized array, then:
true
returns a normal array.
false
returns the array, first ([0]
) element of which contains serialized array string.Default: false
Examples
#1 Example of using this function inside the Loop.
The example below shows how to use this function to get the value of thumb
custom field. The value contains a link to a thumbnail image.
<?php $thumb = get_post_meta( $post->ID, 'thumb', true ); if ( $thumb ) { ?> <a href="<?php the_permalink() ?>" rel="bookmark"> <img class="thumb" src="<?php echo $thumb ?>" alt="<?php the_title(); ?>" /> </a> <?php } ?>
#2 You no longer need this function
Since WP 3.5, you can just call
$post->meta_key
it is the same as:
get_post_meta( $post->ID, 'meta_key', true )
This makes code a lot cleaner and more readable.
if( some_condiltion ) { $value = $post->_wp_page_template ?: 'not assigned'; }
If there are multiple values for the key “meta_key”, $post->meta_key
will only return the first value. get_post_meta( $post_id, 'meta_key')
will return all the values. Multiple values can be added using the add_post_meta() function.
#3 Check existence of a specified metafield
When you need to check whether a field exists (has any value: empty string or 0):
$metas = get_post_meta( $post->ID ); if( isset($metas['key_name']) ){ echo 'The meta field "key_name" exists.'; }
#4 Get all custom fields of the post
If you do not specify a meta key, the function will return all meta fields of the post.
If the value is serialised, it will be retrieved as a string, i.e. you have to de-serialise it yourself:
$post_metas = get_post_meta( 76 ); /* Array ( [_edit_lock] => Array ( [0] => 1517175359:1 ) [_edit_last] => Array ( [0] => 1 ) [views] => Array ( [0] => 10164 ) [_thumbnail_id] => Array ( [0] => 9556 ) [photo] => Array ( [0] => https://example.com/wp-content/uploads/2010/03/Quicktags-API.png [1] => https://example.com/wp-content/uploads/2017/07/image.png ) [serialized_value] => Array ( [0] => a:2:{s:4:"name";s:6:"hexlet";s:4:"type";s:5:"admin";} ) ) */
We can make it into string:
$post_metas = get_post_meta( 76 ); $post_metas = array_combine( array_keys( $post_metas ), array_column( $post_metas, '0' ) ); /* Now output will be like here: Array ( [_edit_lock] => 1517175359:1 [_edit_last] => 1 [views] => 10164 [_thumbnail_id] => 9556 [photo] => https://example.com/wp-content/uploads/2010/03/Quicktags-API.png ) */
#5 Other example of using custom fields functions
#6 Counting the number of all custom fields of all posts
This example shows how to print all unique custom fields in one query and calculate how many of them are used in the database. This query can be useful for the profiling of post custom fields:
global $wpdb; $data = $wpdb->get_results(" SELECT meta_key, count(*) as count FROM $wpdb->postmeta WHERE meta_key NOT LIKE '\_oembed%' GROUP BY meta_key "); print_r( $data ); /* Array ( [0] => stdClass Object ( [meta_key] => _edit_lock [count] => 2300 ) [1] => stdClass Object ( [meta_key] => _edit_last [count] => 2123 ) ... ) */
#7 Get an aGet an array of values of custom fields
Get the values of post 76 meta fields key_1
; assumed that the post has several custom fields with this key:
$values = get_post_meta( 76, 'key_1' ); /* Array ( [0] => value 1 [1] => value 2 ) */
#8 Retrieve only one custom field
If there are several custom fields with the same key, to get only the first one (in a string), set $single to true:
$value = get_post_meta( 76, 'key_1', true ); //> value 1
#9 Join all metafields into an object
This example shows how you can combine all custom fields of a post, to then use them in convenient way.
You may need it when you supposed to use a lot of different post custom fields in one code. It is not convenient to get each value with this function, but it is more convenient to get all the fields once, create an object from them and then take the data from the object - this works faster, and your code become clearer.
It is assumed that the keys of custom fields are in latin and the field with one key has only one value:
// collect meta to object $meta = new stdClass; foreach( (array) get_post_meta( $post->ID ) as $k => $v ) $meta->$k = $v[0]; // Now, let's say the post has metafield 'book' // Get it like so: echo $meta->book;
Also, you can get the value of postmeta directly from WP_Post object: $post->my_meta_key
. $post here is a WP_Post object and my_meta_key
the name of metafield which value you want to get.
#10 Checking that the meta-field exists
Return values when no meta field is found
If a meta field with the given $key isn’t found for the given $post_id, the return value varies:
If $single = true
, an empty string
is returned.
If $single = false
, an empty array
is returned.
Since both evaluate as false, you can use get_post_meta directly in conditionals, like this:
$value = get_post_meta( 76, 'key_1', true ); // single if( $value ){ // the meta-field exists } $value = get_post_meta( 76, 'key_1' ); // multiple if( $value ){ // the meta-field exists }
This code the same as:
$value = get_post_meta( 76, 'key_1', true ); if( '' !== $value ){ // the meta-field is } $value = get_post_meta( 76, 'key_1' ); if( [] !== $value ){ // the meta-field is }
What if I want to store an empty string?
If for some reason your with to store an empty string or array into your meta field, get_post_meta() will not be reliable when checking if the given meta field exists.
In this case, you can use get_post_custom_keys() to do so:
$post_id = 1; $meta_exists = in_array( 'key_1', get_post_custom_keys( $post_id ), true ); if( $meta_exists ) { // this correctly checks for the existence of the given key, // even if it's empty or has a value that evaluates as false. }
#11 Default Usage
Get the meta for all keys for the current post:
$meta = get_post_meta( $post_id );
Get all meta for a single key for the current post:
$key_1_values = get_post_meta( $post_id, 'key_1' );
Get the first value of a meta key for the current post:
$key_1_value = get_post_meta( $post_id, 'key_1', true );
#12 Don’t specify a $key and set $single = true
In this case function will return all keys still with an array of values.
$meta = get_post_meta( $post_id, '', true ); print_r( $meta ); /* Array ( [key_1] => Array ( [0] => value_1 ), [key_2] => Array ( [0] => value_2 ) ) */
Changelog
Since 1.5.0 | Introduced. |
get_post_meta() get post meta code WP 6.7.1
function get_post_meta( $post_id, $key = '', $single = false ) { return get_metadata( 'post', $post_id, $key, $single ); }