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.

IMPORTANT! The function checks whether specified post ID is not a revision. If a revision ID is specified, the ID is changed to revision's parent post ID. It means that metadata is always added for main post, and never for revision.

IMPORTANT! The function expects slashed string in the $meta_key and $meta_value parameters. It means that specified values of those parameters are processed by wp_unslash() function before insert into the DB.

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

Uses: add_metadata()

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

0

#1 Basic usage

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

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

#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(...) )
0

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

#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.');
...
0

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

Changelog

Since 1.5.0 Introduced.

add_post_meta() code WP 6.5.2

wp-includes/post.php 
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 );
}

Metadatas (any)