add_metadata

Add metadata for the specified object.

Description

(int|false) add_metadata( (string) $meta_type, (int) $object_id, (string) $meta_key, (mixed) $meta_value, (constant) $unique = false ); 

Returns (int|false)

The meta ID on success, 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. $unique — Optional. (constant) => false
Optional, default is false. Whether the specified metadata key should be unique for the object. If true, and the object already has a value for the specified metadata key, no change will be made.

Usage

  1. if ( !function_exists( 'add_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. $unique = false; 
  16.  
  17. // NOTICE! Understand what this does before running. 
  18. $result = add_metadata($meta_type, $object_id, $meta_key, $meta_value, $unique); 
  19.  

Defined (1)

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

/wp-includes/meta.php  
  1. function add_metadata($meta_type, $object_id, $meta_key, $meta_value, $unique = false) { 
  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.  
  17. // expected_slashed ($meta_key) 
  18. $meta_key = wp_unslash($meta_key); 
  19. $meta_value = wp_unslash($meta_value); 
  20. $meta_value = sanitize_meta( $meta_key, $meta_value, $meta_type ); 
  21.  
  22. /** 
  23. * Filters whether to add metadata of a specific type. 
  24. * The dynamic portion of the hook, `$meta_type`, refers to the meta 
  25. * object type (comment, post, or user). Returning a non-null value 
  26. * will effectively short-circuit the function. 
  27. * @since 3.1.0 
  28. * @param null|bool $check Whether to allow adding metadata for the given type. 
  29. * @param int $object_id Object ID. 
  30. * @param string $meta_key Meta key. 
  31. * @param mixed $meta_value Meta value. Must be serializable if non-scalar. 
  32. * @param bool $unique Whether the specified meta key should be unique 
  33. * for the object. Optional. Default false. 
  34. */ 
  35. $check = apply_filters( "add_{$meta_type}_metadata", null, $object_id, $meta_key, $meta_value, $unique ); 
  36. if ( null !== $check ) 
  37. return $check; 
  38.  
  39. if ( $unique && $wpdb->get_var( $wpdb->prepare( 
  40. "SELECT COUNT(*) FROM $table WHERE meta_key = %s AND $column = %d",  
  41. $meta_key, $object_id ) ) ) 
  42. return false; 
  43.  
  44. $_meta_value = $meta_value; 
  45. $meta_value = maybe_serialize( $meta_value ); 
  46.  
  47. /** 
  48. * Fires immediately before meta of a specific type is added. 
  49. * The dynamic portion of the hook, `$meta_type`, refers to the meta 
  50. * object type (comment, post, or user). 
  51. * @since 3.1.0 
  52. * @param int $object_id Object ID. 
  53. * @param string $meta_key Meta key. 
  54. * @param mixed $meta_value Meta value. 
  55. */ 
  56. do_action( "add_{$meta_type}_meta", $object_id, $meta_key, $_meta_value ); 
  57.  
  58. $result = $wpdb->insert( $table, array( 
  59. $column => $object_id,  
  60. 'meta_key' => $meta_key,  
  61. 'meta_value' => $meta_value 
  62. ) ); 
  63.  
  64. if ( ! $result ) 
  65. return false; 
  66.  
  67. $mid = (int) $wpdb->insert_id; 
  68.  
  69. wp_cache_delete($object_id, $meta_type . '_meta'); 
  70.  
  71. /** 
  72. * Fires immediately after meta of a specific type is added. 
  73. * The dynamic portion of the hook, `$meta_type`, refers to the meta 
  74. * object type (comment, post, or user). 
  75. * @since 2.9.0 
  76. * @param int $mid The meta ID after successful update. 
  77. * @param int $object_id Object ID. 
  78. * @param string $meta_key Meta key. 
  79. * @param mixed $meta_value Meta value. 
  80. */ 
  81. do_action( "added_{$meta_type}_meta", $mid, $object_id, $meta_key, $_meta_value ); 
  82.  
  83. return $mid;