get_post_meta() │ WP 1.5.0

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
}
?>

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.';
}

/**
 * This function handles the mood and listening_to meta tags.
 * It can be called with an action of update, delete, and get (default)
 * When called with an action of update, either $mood or $listening_to must be provided.
 * i.e. mood_music( $post->ID, 'update', 'Happy', 'Bon Jovi - It's My Life' );
 */
function mood_music( $post_id, $action = 'get', $mood = 0, $listening_to = 0 ){

	//Let's make a switch to handle the three cases of 'Action'
	switch( $action ){
		case 'update' :
			//If nothing is given to update, end here
			if( ! $mood && ! $listening_to ){
				return false;
			}

			//add_post_meta usage:
			//add_post_meta( $post_id, $meta_key, $meta_value, $unique = false )

			//If the $mood variable is supplied,
			//add a new key named 'mood', containing that value.
			//If the 'mood' key already exists on this post,
			//this command will simply add another one.
			if( $mood ){
				add_post_meta( $post_id, 'mood', $mood );

				return true;
			}

			//update_post_meta usage:
			//update_post_meta( $post_id, $meta_key, $meta_value )

			//If the $listening_to variable is supplied,
			//add a new key named 'listening_to', containing that value.
			//If the 'listening_to' key already exists on this post,
			//this command will update it to the new value
			if( $listening_to ){
				add_post_meta( $post_id, 'listening_to', $listening_to, true ) or
				update_post_meta( $post_id, 'listening_to', $listening_to );

				return true;
			}

			break;

		case 'delete' :
			//delete_post_meta usage:
			//delete_post_meta( $post_id, $meta_key, $prev_value = ' ' )

			//This will delete all instances of the following keys from the given post
			delete_post_meta( $post_id, 'mood' );
			delete_post_meta( $post_id, 'listening_to' );

			//To only delete 'mood' if it's value is 'sad':
			//delete_post_meta( $post_id, 'mood', 'sad' );
			break;

		case 'get' :
			//get_post_custom usage:
			//get_post_meta( $post_id, $meta_key, $single value = false )

			//$stored_moods will be an array containing all values of the meta key 'mood'
			$stored_moods = get_post_meta( $post_id, 'mood' );
			//$stored_listening_to will be the first value of the key 'listening_to'
			$stored_listening_to = get_post_meta( $post_id, 'listening_to', 'true' );

			//Now we need a nice ouput format, so that
			//the user can implement it how he/she wants:
			//ie. echo mood_music( $post->ID, 'get' );

			$return = '<div class="mood-music">';

			if( ! empty( $stored_moods ) ){
				$return .= '<strong>Current Mood</strong>: ';
			}

			foreach( $stored_moods as $mood ){
				$return .= $mood . ', ';
			}

			$return .= '<br/>';

			if( ! empty( $stored_listening_to ) ){
				$return .= '<strong>Currently Listening To</strong>: ';
				$return .= $stored_listening_to;
			}
			$return .= '</div>';

			return $return;

			break;
		default :
			return false;
	}

}

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
		)
	...
)
*/

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
)
*/

If you do not specify a meta key, the function will return all meta fields of the post:

$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
		)

)
*/

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
)
*/

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

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;

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. 
} 

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';
}

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 );

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 ) 
)
*/