add_post_meta() │ WP 1.5.0

Adds meta field to the specified post.

The function should be used when several meta fields with the same keys are used. To do this, the function has a parameter $unique, which is false by default, it means that by default, a non-unique key is created, it means that there can be many fields with the same keys.

In other cases, the update_post_meta() function can be used it is more universal. It is often more convenient because at the same time it: updates the field if it exists or creates a new one if there is no such field.

Post meta data is called "Custom Fields" on the Administration Screen.

No Hooks.

Return

Int|false. Meta ID on success, false on failure.

Usage

add_post_meta( $post_id, $meta_key, $meta_value, $unique );

$post_id(int) (required)

Post ID, to which we want add meta field.

$meta_key(string) (required)

Meta field name (key).

$meta_value(mixed) (required)

Meta field value.

$unique(true/false)

Whether the same key should not be added.

• true - unique (only one)
• false - not unique. There can be many fields with same key.

If this parameter is set to true, then the field will be checked first whether there is already a field with the same key, if there is, then the field will not be added.
Default: false

Examples

#1 Basic usage

Add a custom field "my_key" with the value 47, to the post 68:

add_post_meta( 68, 'my_key', 47 );

#2 Add or update a unique custom field

Add a meta field if the field does not exist yet or update the existing one. It is important to understand that if the $unique parameter is true, the field will not be updated if it already exists (example below).

add_post_meta( 7, 'fruit', 'banana', true ) OR update_post_meta( 7, 'fruit', 'banana' );

to do this, use this variant:

if ( !update_post_meta(...) ) add_post_meta(...) )

#3 Add a field only if it is not already exists

If we want to be sure that the fields with the key "my_key" do not exist before adding it:

add_post_meta( 68, 'my_key', '47', true );

#4 Multiple fields with the same keys

Here is an example that allows us to add several meta fields with the same key "my_key":

add_post_meta( 68, 'my_key', 47 );
add_post_meta( 68, 'my_key', 682 );
add_post_meta( 68, 'my_key', 'The quick, brown fox jumped over the lazy dog.');
...

Creating system (hidden) custom fields

If you are a developer and you need to create a custom field that will not be visible to users, but will work as a normal custom field, then you should know that WordPress does not show custom fields starting with _ (underscore). Does not show means that they are ignored on the post editing page or when using the_meta() template function.

Therefore, if you suddenly need to hide a custom field, you need to create a field with a key starting with _.

For example, let's add a unique custom field _color with a value of red and this field will not be displayed in the admin on the edit post page:

add_post_meta( 68, '_color', 'red', true );

function add_post_meta( $post_id, $meta_key, $meta_value, $unique = false ) {
	// Make sure meta is added to the post, not a revision.
	$the_post = wp_is_post_revision( $post_id );
	if ( $the_post ) {
		$post_id = $the_post;
	}

	return add_metadata( 'post', $post_id, $meta_key, $meta_value, $unique );
}