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.
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
#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 );
Code of add post meta:
wp-includes/post.php
VER 5.0.3
Related Functions
From tag: Metadatas (any)
- add_comment_meta()
- add_metadata()
- add_term_meta()
- add_user_meta()
- delete_comment_meta()
- delete_metadata()
- delete_post_meta()
- delete_term_meta()
- delete_user_meta()
- get_comment_meta()