WordPress update_post_meta

Updates the specified arbitrary field (meta-field) of the specified record (post) or adds a new one.

The function can be used instead of add_post_meta() because it first checks if the arbitrary field exists in the specified post; if it is not found, control is fully passed to add_post_meta().

If an array is passed to $meta_value, it will automatically be written as a serialized string, i.e., there is no need to process the array with serialize() before passing it to $meta_value.

IMPOrTANT: The function checks if the specified record (post ID) is a revision. If it is a revision, the ID is changed to the ID of the parent record. I.e. metadata will be updated at parent record (not at revision) in any case.

IMPORTANT: The function expects an escaped string in the parameters $meta_key and $meta_value. That is, the values of arbitrary fields are processed by the wp_unslash() function before they are written to the database. For more details, see: "Screening in values of arbitrary fields".

Works based on: update_metadata()
Base for: update_attached_file(), set_post_thumbnail(), wp_update_attachment_metadata()
1 time – 0.001327 sec (very slow) | 50,000 times – 42.23 sec (very slow) | PHP 7.0.8, WP 4.6.1
No hooks.

Returns

int|true|false.

• true – if update was successful.
• false – when it failed. Or when the same field value was passed (as in the database).
• The primary field ID of the meta field table (meta_id) when a new field was created.

Using

update_post_meta( $post_id, $meta_key, $meta_value, $prev_value );

$post_id(number) (mandatory)
The ID of the post whose arbitrary field you want to update/create.
$meta_key(string) (mandatory)
The key of the arbitrary field to be updated/created.
$meta_value(string/array) (mandatory)
The new, arbitrary field value to update/create. If you pass an array, the value will be serialized to a string.
$prev_value(string/array)
The value of the arbitrary field we want to change. Needed for when a post has multiple arbitrary fields with the same keys. If you do not specify this parameter and the post has multiple fields with the same keys, all fields will be updated.
Default: ”

Examples

1. Let’s update arbitrary field my_key, post 76

Replace the value we have there with Steve:

update_post_meta( 76, 'my_key', 'Steve' );

1. 2 Examples of operations on fields

Suppose that post 76 has the following 4 arbitrary fields, with values:

key_1 = Happy
key_1 = Sad
key_2 = Gregory
my_key = Steve

Let’s change the value of the key_2 field to Hans:

update_post_meta( 76, 'key_2', 'Hans' );

Change the value of the key_1 field from Sad to Happy:

update_post_meta( 76, 'key_1', 'Happy', 'Sad' );

Now, we have these fields:

key_1 = Happy
key_1 = Happy
key_2 = Hans
my_key = Steve

Let’s change the value of the first field key_1 from Happy to Excited:

update_post_meta( 76, 'key_1', 'Excited', 'Happy' );

//or
update_post_meta( 76, 'key_1', 'Excited' );

// This use, will update only the first field (only one)!
// To update all fields with the key "key_1" to Excited, you have to apply the function to each field, e.g. with 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 Let’s change the permanent page template file.

The template file for the permanent page is written in the system arbitrary field _wp_page_template:

update_post_meta( $id, '_wp_page_template', 'new_template.php' );