添加指定对象的元数据。

原型

add_metadata( string $meta_type, int $object_id, string $meta_key, mixed $meta_value, bool $unique = false )

参数

$meta_type (string) (Required) 对象元数据的类型用于(例如,评论,帖子,术语或用户)。

$object_id (int) (Required) 对象元数据的ID用于

$meta_key (string) (Required) 元数据键

$meta_value (mixed) (Required) 元数据价值。如果是非标量,则必须可序列化。

$unique (bool) (Optional)                             指定的元数据键是否应该对象是唯一的。如果为true,并且对象已具有指定元数据键的值,则不会进行任何更改。

返回值

(int|false)  成功时的元ID,失败时的假。

源文件

路径:wp-includes/meta.php

<?php
...
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 );
	/**
	 * Filters whether to add metadata of a specific type.
	 *
	 * The dynamic portion of the hook, `$meta_type`, refers to the meta
	 * object type (comment, post, term, or user). Returning a non-null value
	 * will effectively short-circuit the function.
	 *
	 * @since 3.1.0
	 *
	 * @param null|bool $check      Whether to allow adding metadata for the given type.
	 * @param int       $object_id  Object ID.
	 * @param string    $meta_key   Meta key.
	 * @param mixed     $meta_value Meta value. Must be serializable if non-scalar.
	 * @param bool      $unique     Whether the specified meta key should be unique
	 *                              for the object. Optional. Default false.
	 */
	$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, `$meta_type`, refers to the meta
	 * object type (comment, post, term, or user).
	 *
	 * @since 3.1.0
	 *
	 * @param int    $object_id  Object ID.
	 * @param string $meta_key   Meta key.
	 * @param mixed  $meta_value Meta 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, `$meta_type`, refers to the meta
	 * object type (comment, post, term, or user).
	 *
	 * @since 2.9.0
	 *
	 * @param int    $mid        The meta ID after successful update.
	 * @param int    $object_id  Object ID.
	 * @param string $meta_key   Meta key.
	 * @param mixed  $meta_value Meta value.
	 */
	do_action( "added_{$meta_type}_meta", $mid, $object_id, $meta_key, $_meta_value );
	return $mid;
}
...
?>

其他

英文文档:https://developer.wordpress.org/reference/functions/add_metadata/