WordPress.org

Languages: English • post meta 日本語 (Add your language)

Description

The function update_post_meta() updates the value of an existing meta key (custom field) for the specified post.

This may be used in place of add_post_meta() function. The first thing this function will do is make sure that $meta_key already exists on $post_id. If it does not, add_post_meta($post_id, $meta_key, $meta_value) is called instead and its result is returned.

Returns meta_id if the meta doesn't exist, otherwise returns true on success and false on failure. It also returns false if the value submitted is the same as the value that is already in the database.

Please note that if your database collation is case insensitive (has with suffix _ci) then update_post_meta and delete_post_meta and get_posts will update/delete/query the meta records with keys that are upper or lower case. However get_post_meta will apparently be case sensitive due to WordPress caching. See https://core.trac.wordpress.org/ticket/18210 for more info.

Usage

 <?php update_post_meta( $post_id, $meta_key, $meta_value, $prev_value ); ?> 

Parameters

$post_id

(integer) (required) The ID of the post which contains the field you will edit.

Default: None

$meta_key

(string) (required) The key of the custom field you will edit. (this should be raw as opposed to sanitized for database queries)

Default: None

$meta_value

(mixed) (required) The new value of the custom field. A passed array will be serialized into a string.(this should be raw as opposed to sanitized for database queries)

Default: None

$prev_value

(mixed) (optional) The old value of the custom field you wish to change. This is to differentiate between several fields with the same key. If omitted, and there are multiple rows for this post and meta key, all meta values will be updated.

Default: Empty

Return Values

(mixed) 

Returns meta_id if the meta doesn't exist, otherwise returns true on success and false on failure. NOTE: If the meta_value passed to this function is the same as the value that is already in the database, this function returns false.

Examples

Default Usage

<?php update_post_meta( 76, 'my_key', 'Steve' ); ?>

Other Examples

Assuming a post has an ID of 76, and the following 4 custom fields:

To change key_2's value to Hans:

<?php update_post_meta( 76, 'key_2', 'Hans' ); ?>

To change key_1's value from Sad to Happy:

<?php update_post_meta( 76, 'key_1', 'Happy', 'Sad' ); ?>

The fields would now look like this:

Note: This function will update only the first field that matches the criteria.

To change the first key_1's value from Happy to Excited:

<?php 
  update_post_meta( 76, 'key_1', 'Excited', 'Happy' );

  //Or

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

  //To change all fields with the key "key_1":

  $key1_values = get_post_custom_values( 'key_1', 76 );
  foreach ( $key1_values as $value )
    update_post_meta( 76, 'key_1', 'Excited', $value );
?>

Edit Page template

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

For a more detailed example, go to the post_meta Functions Examples page.

Character Escaping

Post meta values are passed through the stripslashes() function upon being stored, so you will need to be careful when passing in values (such as JSON) that might include \ escaped characters.

Do not store escaped values

Consider the JSON value {"key":"value with \"escaped quotes\""}:

<?php
$escaped_json = '{"key":"value with \\"escaped quotes\\""}';
update_post_meta( $id, 'escaped_json', $escaped_json );
$broken = get_post_meta( $id, 'escaped_json', true );
/*
$broken, after passing through stripslashes() ends up unparsable:
{"key":"value with "escaped quotes""}
*/
?>

Workaround

By adding one more level of \ escaping using function wp_slash (introduced in WP 3.6), you can compensate for the call to stripslashes():

<?php
$escaped_json = '{"key":"value with \\"escaped quotes\\""}';
update_post_meta( $id, 'double_escaped_json', wp_slash( $escaped_json ) );
$fixed = get_post_meta( $id, 'double_escaped_json', true );
/*
$fixed, after stripslashes(), ends up being stored as desired:
{"key":"value with \"escaped quotes\""}
*/
?>

Notes

• This function uses update_metadata().

Source Code

update_post_meta() is located in wp-includes/post.php

Change Log

Since 1.5.0

Related

Custom Fields: the_meta(), get_post_meta(), add_post_meta(), update_post_meta(), delete_post_meta(), get_post_custom(), get_post_custom_values(), get_post_custom_keys() (See Also: post_meta Function Examples)