WordPress Version: 6.3
/**
* Adds metadata for the specified object.
*
* @since 2.9.0
*
* @global wpdb $wpdb WordPress database abstraction object.
*
* @param string $meta_type Type of object metadata is for. Accepts 'post', 'comment', 'term', 'user',
* or any other object type with an associated meta table.
* @param int $object_id ID of the object metadata is for.
* @param string $meta_key Metadata key.
* @param mixed $meta_value Metadata value. Must be serializable if non-scalar.
* @param bool $unique Optional. 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. Default false.
* @return int|false The meta ID on success, false on failure.
*/
function add_metadata($meta_type, $object_id, $meta_key, $meta_value, $unique = false)
{
global $wpdb;
if (!$meta_type || !$meta_key || !is_numeric($object_id)) {
return false;
}
$object_id = absint($object_id);
if (!$object_id) {
return false;
}
$table = _get_meta_table($meta_type);
if (!$table) {
return false;
}
$meta_subtype = get_object_subtype($meta_type, $object_id);
$column = sanitize_key($meta_type . '_id');
// expected_slashed ($meta_key)
$meta_key = wp_unslash($meta_key);
$meta_value = wp_unslash($meta_value);
$meta_value = sanitize_meta($meta_key, $meta_value, $meta_type, $meta_subtype);
/**
* Short-circuits adding metadata of a specific type.
*
* The dynamic portion of the hook name, `$meta_type`, refers to the meta object type
* (post, comment, term, user, or any other type with an associated meta table).
* Returning a non-null value will effectively short-circuit the function.
*
* Possible hook names include:
*
* - `add_post_metadata`
* - `add_comment_metadata`
* - `add_term_metadata`
* - `add_user_metadata`
*
* @since 3.1.0
*
* @param null|bool $check Whether to allow adding metadata for the given type.
* @param int $object_id ID of the object metadata is for.
* @param string $meta_key Metadata key.
* @param mixed $meta_value Metadata value. Must be serializable if non-scalar.
* @param bool $unique Whether the specified meta key should be unique for the object.
*/
$check = apply_filters("add_{$meta_type}_metadata", null, $object_id, $meta_key, $meta_value, $unique);
if (null !== $check) {
return $check;
}
if ($unique && $wpdb->get_var($wpdb->prepare("SELECT COUNT(*) FROM {$table} WHERE meta_key = %s AND {$column} = %d", $meta_key, $object_id))) {
return false;
}
$_meta_value = $meta_value;
$meta_value = maybe_serialize($meta_value);
/**
* Fires immediately before meta of a specific type is added.
*
* The dynamic portion of the hook name, `$meta_type`, refers to the meta object type
* (post, comment, term, user, or any other type with an associated meta table).
*
* Possible hook names include:
*
* - `add_post_meta`
* - `add_comment_meta`
* - `add_term_meta`
* - `add_user_meta`
*
* @since 3.1.0
*
* @param int $object_id ID of the object metadata is for.
* @param string $meta_key Metadata key.
* @param mixed $_meta_value Metadata value.
*/
do_action("add_{$meta_type}_meta", $object_id, $meta_key, $_meta_value);
$result = $wpdb->insert($table, array($column => $object_id, 'meta_key' => $meta_key, 'meta_value' => $meta_value));
if (!$result) {
return false;
}
$mid = (int) $wpdb->insert_id;
wp_cache_delete($object_id, $meta_type . '_meta');
/**
* Fires immediately after meta of a specific type is added.
*
* The dynamic portion of the hook name, `$meta_type`, refers to the meta object type
* (post, comment, term, user, or any other type with an associated meta table).
*
* Possible hook names include:
*
* - `added_post_meta`
* - `added_comment_meta`
* - `added_term_meta`
* - `added_user_meta`
*
* @since 2.9.0
*
* @param int $mid The meta ID after successful update.
* @param int $object_id ID of the object metadata is for.
* @param string $meta_key Metadata key.
* @param mixed $_meta_value Metadata value.
*/
do_action("added_{$meta_type}_meta", $mid, $object_id, $meta_key, $_meta_value);
return $mid;
}