get_post_meta() WP 1.5.0
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
String/array.
-
Returns
false
when $post_id parameter passed wrongly. -
If $single = true
string/array
— when metafield exists.''
— when metafield not exists.
- If $single = false
array of all metafield values
— when metafield exists.array()
— when metafield not exists.
If a number is stored in metafield value 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 name of meta field, the value of which 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. Get 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 ) */
#1.1. 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:
$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 ) ) */
#2. 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
#3. 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.
#4. 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 if ( $thumb = get_post_meta( $post->ID, 'thumb', true ) ) : ?> <a href="<?php the_permalink() ?>" rel="bookmark"> <img class="thumb" src="<?php echo $thumb ?>" alt="<?php the_title(); ?>" /> </a> <?php endif; ?>
#5. 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.'; }
#6. Other example of using custom fields functions
#7. Output 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 ) ... ) */
Changelog
Since 1.5.0 | Introduced. |
Code of get_post_meta() get post meta WP 5.6
function get_post_meta( $post_id, $key = '', $single = false ) {
return get_metadata( 'post', $post_id, $key, $single );
}Related Functions
From tag: Metadatas (any)
- add_comment_meta()
- add_metadata()
- add_post_meta()
- add_term_meta()
- add_user_meta()
- delete_comment_meta()
- delete_metadata()
- delete_post_meta()
- delete_term_meta()
- delete_user_meta()
- get_comment_meta()