update_post_meta()
Updates specified meta field of specified post. Or adds it, if it's not exists.
Can be used in place of add_post_meta(). Because, at first the function checks whether the post has specified meta field, if it hasn't then the control is fully delegates to the add_post_meta() function.
If you pass an array to the $meta_value value, it will be automatically written as a serialized string, i.e. it is no need to process the array with the serialize() function before passing it to the $meta_value parameter.
IMPORTANT! The function checks whether specified post ID is not a revision. If a revision ID is passed, the ID will be changed to revision's parent post ID. It means that metadata is always updated 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.
No Hooks.
Return
Int|true|false.
true- on successful update.false- on failure. Or when the same field value was passed (as in the database).meta_id(ID of primary key field of postmeta table), if a field with the given key didn't exist and was therefore added.
Usage
update_post_meta( $post_id, $meta_key, $meta_value, $prev_value );
- $post_id(int) (required)
- Post ID, for which the metadata need to be updated/created.
- $meta_key(string) (required)
- Meta key. Metadata name.
- $meta_value(mixed) (required)
- Metadata value. If an array is passed, the value will be serialized to a string.
- $prev_value(mixed)
- Previous value to check before updating. The meta value we want to change. This parameter is needed for cases when the post has several meta fields with the same key. If don't specify this parameter and the post has several meta fields with the same key, values of all those fields will be updated.
Default: ''
Examples
#1 Update my_key meta field of the post 76
Update the existing value to Steve:
update_post_meta( 76, 'my_key', 'Steve' );
#2 Other examples of changing post metadata
Suppose that the post 76 has 4 custom fields with the following values:
key_1 = Happy key_1 = Sad key_2 = Gregory my_key = Steve
Change the value of field key_2 to Hans:
update_post_meta( 76, 'key_2', 'Hans' );
Change the value of field key_1 from Sad to Happy:
update_post_meta( 76, 'key_1', 'Happy', 'Sad' );
Now, we have the following meta values:
key_1 = Happy key_1 = Happy key_2 = Hans my_key = Steve
Change the value of the first metafield key_1 from Happy to Excited:
update_post_meta( 76, 'key_1', 'Excited', 'Happy' ); // or update_post_meta( 76, 'key_1', 'Excited' ); // Such use, will update only the first field (only one)! // To update all fields with "key_1" key to "Excited", you need to apply the function to each field, for example using a loop: $key1_values = get_post_custom_values( 'key_1', 76 ); foreach( $key1_values as $value ) update_post_meta( 76, 'key_1', 'Excited', $value );
#3 More examples
#4 Change the static page template file
The static page template file name is written to the system meta field _wp_page_template:
update_post_meta( $id, '_wp_page_template', 'new-template.php' );
Changelog
| Since 1.5.0 | Introduced. |
update_post_meta() update post meta code WP 6.5.2
function update_post_meta( $post_id, $meta_key, $meta_value, $prev_value = '' ) {
// Make sure meta is updated for the post, not for a revision.
$the_post = wp_is_post_revision( $post_id );
if ( $the_post ) {
$post_id = $the_post;
}
return update_metadata( 'post', $post_id, $meta_key, $meta_value, $prev_value );
}