# add_metadata()

URL: https://chugunov.pro/api-wordpress/functions/add_metadata/
Проверено на WordPress 6.9, обновлено 06.08.2026.
Источник: независимый русскоязычный справочник chugunov.pro. Не является официальной документацией WordPress.

Тип: функция.
Появился в версии: 2.9.0.

## Сигнатура

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

## Описание

По историческим причинам и ключ метаданных, и значение метаданных на входе должны быть «экранированы обратными слэшами».

## Параметры

- `$meta_type` `string` — обязательный. Тип объекта, к которому относятся метаданные. Принимает 'blog', 'post', 'comment', 'term', 'user' или любой другой тип объекта со связанной таблицей метаданных.
- `$object_id` `int` — обязательный. ID объекта, к которому относятся метаданные.
- `$meta_key` `string` — обязательный. Ключ метаданных.
- `$meta_value` `mixed` — обязательный. Значение метаданных. Массивы и объекты сохраняются как сериализованные данные и возвращаются того же типа при получении. Остальные типы данных сохраняются в базе данных как строки:
  
  false сохраняется и возвращается как пустая строка ('')
  
  true сохраняется и возвращается как '1'
  
  числа (как целые, так и с плавающей точкой) сохраняются и возвращаются как строки. Должно быть сериализуемым, если не является скалярным значением.
- `$unique` `bool` — необязательный, по умолчанию `false`. Должен ли указанный ключ метаданных быть уникальным для объекта.
  
  Если true и у объекта уже есть значение для указанного ключа метаданных, изменения не вносятся.

## Возвращаемое значение

`int|false`

## Исходный код

Файл: `wp-includes/meta.php:40`

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

	/**
	 * Short-circuits adding metadata of a specific type.
	 *
	 * The dynamic portion of the hook name, `$meta_type`, refers to the meta object type
	 * (blog, 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_blog_metadata`
	 *  - `add_post_metadata`
	 *  - `add_comment_metadata`
	 *  - `add_term_metadata`
	 *  - `add_user_metadata`
	 *
	 * @since 3.1.0
	 *
	 * @param null|int|false $check      Whether to allow adding metadata for the given type. Return false or a meta ID
	 *                                   to short-circuit the function. Return null to continue with the default behavior.
	 * @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
	 * (blog, post, comment, term, user, or any other type with an associated meta table).
	 *
	 * Possible hook names include:
	 *
	 *  - `add_blog_meta`
	 *  - `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
	 * (blog, post, comment, term, user, or any other type with an associated meta table).
	 *
	 * Possible hook names include:
	 *
	 *  - `added_blog_meta`
	 *  - `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;
}
```

## История изменений

- 2.9.0 — Introduced.

## Связанные

Использует: [`get_object_subtype`](https://chugunov.pro/api-wordpress/functions/get_object_subtype/), [`wp_cache_delete`](https://chugunov.pro/api-wordpress/functions/wp_cache_delete/), [`maybe_serialize`](https://chugunov.pro/api-wordpress/functions/maybe_serialize/), `wpdb::insert`, [`_get_meta_table`](https://chugunov.pro/api-wordpress/functions/_get_meta_table/), [`sanitize_meta`](https://chugunov.pro/api-wordpress/functions/sanitize_meta/), [`wp_unslash`](https://chugunov.pro/api-wordpress/functions/wp_unslash/), [`sanitize_key`](https://chugunov.pro/api-wordpress/functions/sanitize_key/), [`absint`](https://chugunov.pro/api-wordpress/functions/absint/), [`apply_filters`](https://chugunov.pro/api-wordpress/functions/apply_filters/), [`do_action`](https://chugunov.pro/api-wordpress/functions/do_action/), `wpdb::get_var`, `wpdb::prepare`.
Используется в: [`_wp_copy_post_meta`](https://chugunov.pro/api-wordpress/functions/_wp_copy_post_meta/), [`wp_autosave_post_revisioned_meta_fields`](https://chugunov.pro/api-wordpress/functions/wp_autosave_post_revisioned_meta_fields/), [`add_site_meta`](https://chugunov.pro/api-wordpress/functions/add_site_meta/), `WP_REST_Meta_Fields::update_multi_meta_value`, [`add_term_meta`](https://chugunov.pro/api-wordpress/functions/add_term_meta/), [`add_user_meta`](https://chugunov.pro/api-wordpress/functions/add_user_meta/), [`add_post_meta`](https://chugunov.pro/api-wordpress/functions/add_post_meta/), [`add_comment_meta`](https://chugunov.pro/api-wordpress/functions/add_comment_meta/), [`update_metadata`](https://chugunov.pro/api-wordpress/functions/update_metadata/).

Оригинал в официальной документации: https://developer.wordpress.org/reference/functions/add_metadata/