update_metadata

Update metadata for the specified object.

Description

(int|bool) update_metadata( (string) $meta_type, (int) $object_id, (string) $meta_key, (mixed) $meta_value, (string) $prev_value = '' ); 

If no value already exists for the specified object ID and metadata key, the metadata will be added.

Returns (int|bool)

Meta ID if the key didn't exist, true on successful update, false on failure.

Parameters (5)

0. $meta_type (string)
Type of object metadata is for (e.g., comment, post, or user)
1. $object_id (int)
ID of the object metadata is for
2. $meta_key (string)
The meta key.
3. $meta_value (mixed)
Metadata value. Must be serializable if non-scalar.
4. $prev_value — Optional. (string) => ''
If specified, only update existing metadata entries with the specified value. Otherwise, update all entries.

Usage

  1. if ( !function_exists( 'update_metadata' ) ) { 
  2. require_once ABSPATH . WPINC . '/meta.php'; 
  3.  
  4. // Type of object metadata is for (e.g., comment, post, or user) 
  5. $meta_type = ''; 
  6.  
  7. // ID of the object metadata is for 
  8. $object_id = -1; 
  9.  
  10. // The meta key. 
  11. $meta_key = ''; 
  12.  
  13. // Metadata value. Must be serializable if non-scalar. 
  14. $meta_value = null; 
  15.  
  16. // Optional. If specified, only update existing metadata entries with 
  17. // the specified value. Otherwise, update all entries. 
  18. $prev_value = ''; 
  19.  
  20. // NOTICE! Understand what this does before running. 
  21. $result = update_metadata($meta_type, $object_id, $meta_key, $meta_value, $prev_value); 
  22.  

Defined (1)

The function is defined in the following location(s).

/wp-includes/meta.php  
  1. function update_metadata($meta_type, $object_id, $meta_key, $meta_value, $prev_value = '') { 
  2. global $wpdb; 
  3.  
  4. if ( ! $meta_type || ! $meta_key || ! is_numeric( $object_id ) ) { 
  5. return false; 
  6.  
  7. $object_id = absint( $object_id ); 
  8. if ( ! $object_id ) { 
  9. return false; 
  10.  
  11. $table = _get_meta_table( $meta_type ); 
  12. if ( ! $table ) { 
  13. return false; 
  14.  
  15. $column = sanitize_key($meta_type . '_id'); 
  16. $id_column = 'user' == $meta_type ? 'umeta_id' : 'meta_id'; 
  17.  
  18. // expected_slashed ($meta_key) 
  19. $raw_meta_key = $meta_key; 
  20. $meta_key = wp_unslash($meta_key); 
  21. $passed_value = $meta_value; 
  22. $meta_value = wp_unslash($meta_value); 
  23. $meta_value = sanitize_meta( $meta_key, $meta_value, $meta_type ); 
  24.  
  25. /** 
  26. * Filters whether to update metadata of a specific type. 
  27. * The dynamic portion of the hook, `$meta_type`, refers to the meta 
  28. * object type (comment, post, or user). Returning a non-null value 
  29. * will effectively short-circuit the function. 
  30. * @since 3.1.0 
  31. * @param null|bool $check Whether to allow updating metadata for the given type. 
  32. * @param int $object_id Object ID. 
  33. * @param string $meta_key Meta key. 
  34. * @param mixed $meta_value Meta value. Must be serializable if non-scalar. 
  35. * @param mixed $prev_value Optional. If specified, only update existing 
  36. * metadata entries with the specified value. 
  37. * Otherwise, update all entries. 
  38. */ 
  39. $check = apply_filters( "update_{$meta_type}_metadata", null, $object_id, $meta_key, $meta_value, $prev_value ); 
  40. if ( null !== $check ) 
  41. return (bool) $check; 
  42.  
  43. // Compare existing value to new value if no prev value given and the key exists only once. 
  44. if ( empty($prev_value) ) { 
  45. $old_value = get_metadata($meta_type, $object_id, $meta_key); 
  46. if ( count($old_value) == 1 ) { 
  47. if ( $old_value[0] === $meta_value ) 
  48. return false; 
  49.  
  50. $meta_ids = $wpdb->get_col( $wpdb->prepare( "SELECT $id_column FROM $table WHERE meta_key = %s AND $column = %d", $meta_key, $object_id ) ); 
  51. if ( empty( $meta_ids ) ) { 
  52. return add_metadata( $meta_type, $object_id, $raw_meta_key, $passed_value ); 
  53.  
  54. $_meta_value = $meta_value; 
  55. $meta_value = maybe_serialize( $meta_value ); 
  56.  
  57. $data = compact( 'meta_value' ); 
  58. $where = array( $column => $object_id, 'meta_key' => $meta_key ); 
  59.  
  60. if ( !empty( $prev_value ) ) { 
  61. $prev_value = maybe_serialize($prev_value); 
  62. $where['meta_value'] = $prev_value; 
  63.  
  64. foreach ( $meta_ids as $meta_id ) { 
  65. /** 
  66. * Fires immediately before updating metadata of a specific type. 
  67. * The dynamic portion of the hook, `$meta_type`, refers to the meta 
  68. * object type (comment, post, or user). 
  69. * @since 2.9.0 
  70. * @param int $meta_id ID of the metadata entry to update. 
  71. * @param int $object_id Object ID. 
  72. * @param string $meta_key Meta key. 
  73. * @param mixed $meta_value Meta value. 
  74. */ 
  75. do_action( "update_{$meta_type}_meta", $meta_id, $object_id, $meta_key, $_meta_value ); 
  76.  
  77. if ( 'post' == $meta_type ) { 
  78. /** 
  79. * Fires immediately before updating a post's metadata. 
  80. * @since 2.9.0 
  81. * @param int $meta_id ID of metadata entry to update. 
  82. * @param int $object_id Object ID. 
  83. * @param string $meta_key Meta key. 
  84. * @param mixed $meta_value Meta value. 
  85. */ 
  86. do_action( 'update_postmeta', $meta_id, $object_id, $meta_key, $meta_value ); 
  87.  
  88. $result = $wpdb->update( $table, $data, $where ); 
  89. if ( ! $result ) 
  90. return false; 
  91.  
  92. wp_cache_delete($object_id, $meta_type . '_meta'); 
  93.  
  94. foreach ( $meta_ids as $meta_id ) { 
  95. /** 
  96. * Fires immediately after updating metadata of a specific type. 
  97. * The dynamic portion of the hook, `$meta_type`, refers to the meta 
  98. * object type (comment, post, or user). 
  99. * @since 2.9.0 
  100. * @param int $meta_id ID of updated metadata entry. 
  101. * @param int $object_id Object ID. 
  102. * @param string $meta_key Meta key. 
  103. * @param mixed $meta_value Meta value. 
  104. */ 
  105. do_action( "updated_{$meta_type}_meta", $meta_id, $object_id, $meta_key, $_meta_value ); 
  106.  
  107. if ( 'post' == $meta_type ) { 
  108. /** 
  109. * Fires immediately after updating a post's metadata. 
  110. * @since 2.9.0 
  111. * @param int $meta_id ID of updated metadata entry. 
  112. * @param int $object_id Object ID. 
  113. * @param string $meta_key Meta key. 
  114. * @param mixed $meta_value Meta value. 
  115. */ 
  116. do_action( 'updated_postmeta', $meta_id, $object_id, $meta_key, $meta_value ); 
  117.  
  118. return true;