WordPress函数：add_metadata 给指定对象添加附加属性

函数原型：

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

给指定对象添加附加属性

参数说明：

$meta_type，对象数据的类型为。接受'post'、'comment'、'term'、'user'或任何其他具有关联元表的对象类型。

$object_id，对象的ID。

$meta_key， 对象的key。

$meta_value， 属性的值。

$unique，是否保持唯一。指定的元数据键对于对象是否应该是唯一的。如果为true，并且对象已经具有指定元数据键的值，则不会进行任何更改。

函数源码：

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 );

	$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 );

	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' );

	do_action( "added_{$meta_type}_meta", $mid, $object_id, $meta_key, $_meta_value );

	return $mid;
}

包含钩子：

do_action( "added_{$meta_type}_meta", int $mid, int $object_id, string $meta_key, mixed $_meta_value )

do_action( "add_{$meta_type}_meta", int $object_id, string $meta_key, mixed $_meta_value )

apply_filters( "add_{$meta_type}_metadata", null|bool $check, int $object_id, string $meta_key, mixed $meta_value, bool $unique )

使用举例：

function add_comment_location($comment_id, $location) {
	return add_metadata( 'comment', $comment_id, 'location', wp_slash( $location ) );
}