update_post_meta( int $post_id, string $meta_key, mixed $meta_value, mixed $prev_value = '' )

Update post meta field based on post ID.


Description Description

Use the $prev_value parameter to differentiate between meta fields with the same key and post ID.

If the meta field for the post does not exist, it will be added.


Parameters Parameters

$post_id

(int) (Required) Post ID.

$meta_key

(string) (Required) Metadata key.

$meta_value

(mixed) (Required) Metadata value. Must be serializable if non-scalar.

$prev_value

(mixed) (Optional) Previous value to check before removing.

Default value: ''


Top ↑

Return Return

(int|bool) Meta ID if the key didn't exist, true on successful update, false on failure.


Top ↑

Source Source

File: wp-includes/post.php

function update_post_meta( $post_id, $meta_key, $meta_value, $prev_value = '' ) {
	// Make sure meta is added to the post, not a revision.
	if ( $the_post = wp_is_post_revision($post_id) )
		$post_id = $the_post;

	$updated = update_metadata( 'post', $post_id, $meta_key, $meta_value, $prev_value );
	if ( $updated ) {
		wp_cache_set( 'last_changed', microtime(), 'posts' );
	}
	return $updated;
}

Top ↑

Changelog Changelog

Changelog
Version Description
1.5.0 Introduced.


Top ↑

User Contributed Notes User Contributed Notes

  1. Skip to note content
    Contributed by Codex

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

    [key_1] => 'Happy'
    [key_1] => 'Sad'
    [key_2] => 'Gregory'
    [my_key] => 'Steve'

    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:

    [key_1] => 'Happy'
    [key_1] => 'Happy'
    [key_2] => 'Hans'
    [my_key] => 'Steve'

    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]

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

You must log in before being able to contribute a note or feedback.