add_post_meta с версии 1.5.0

Описание

Добавляет произвольное поле для определенного поста/записи.

Для добавления поля можно так же использовать функцию update_post_meta(). Она часто удобнее и работает универсально, обновляет поле или создает новое, если такого поля нет.

add_post_meta() удобнее использовать, когда используются несколько произвольных полей с одинаковыми ключами. Для этого у функции есть параметр $unique (уникальный), который по умолчанию равен false, т.е. по умолчанию создается не уникальный ключ, что означает что таких ключей может быть несколько.

add_post_meta() работает на базе add_metadata().

Функция возвращает true если операция по добавлению поля прошла удачно или false, если поле добавить не удалось.

Использование

<?php add_post_meta($post_id, $meta_key, $meta_value, $unique); ?>

Параметры

$post_id (число) (обязательный)

ID поста, произвольное поле к которому нужно добавить.
По умолчанию: нет

$meta_key (строка) (обязательный)

Название (ключ) произвольного поля.
По умолчанию: нет

$meta_value (строка)

Значение произвольного поля.
По умолчанию: нет

$unique (логический)

true - уникальный (только один), false - не уникальный. Если поставить параметр в true, то при добавлении поля, сначала будет проверяться существует ли уже поле с таким же ключом, если существует, то поле не будет добавлено.
По умолчанию: false

Примеры

1. Базовое использование. Добавим произвольное поле "my_key" со значением 47, к посту 68:

<?php add_post_meta(68, 'my_key', 47); ?>

2. Добавление или обновление уникального произвольного поля.
Добавим произвольное поле, если такое поле еще не существует или обновим существующее. Важно понимать, что если четвертый параметр add_post_meta стоит в true, то поле не будет обновлено, если оно уже существует (пример ниже).

<?php add_post_meta(7, 'fruit', 'banana', true) or update_post_meta(7, 'fruit', 'banana'); ?>

для этого нужно использовать такой вариант:

if ( !update_post_meta(...) ) add_post_meta(...) )

3. Если мы хотим быть уверены, что поля с ключом "my_key" не существует, перед тем как добавлять его:

<?php add_post_meta(68, 'my_key', '47', true); ?>

4. А вот пример, позволяющий добавить нам несколько произвольных полей с одинаковыми ключами "my_key":

<?php add_post_meta(68, 'my_key', '47'); ?>
<?php add_post_meta(68, 'my_key', '682'); ?>
<?php add_post_meta(68, 'my_key', 'The quick, brown fox jumped over the lazy dog.'); ?>
...

Еще примеры можете посмотреть здесь.

Создание системных (спрятанных) произвольных полей

Если вы разработчик и вам нужно создать произвольное поле, которое не будет видно пользователям, но при этом будет работать как обычное произвольное поле, то знайте что WordPress не показывает произвольные поля начинающиеся с "_" (нижнего подчеркивания). Не показывает значит, что они игнорируются на странице редактирования постов или при использовании функции шаблона the_meta().

Поэтому, если нужно вдруг нужно спрятать произвольное поле, то нужно создавать поле с ключом начинающимся с "_", например:

<?php add_post_meta(68, '_color', 'red', true); ?>

добавит уникальное произвольное поле _color со значением red и это поле не будет выводится в админке на странице редактирования постов/постоянных страниц.

add_post_meta()

function add_post_meta($post_id, $meta_key, $meta_value, $unique = false) {
	// make sure meta is added to the post, not a revision
	if ( $the_post = wp_is_post_revision($post_id) )
		$post_id = $the_post;

	return add_metadata('post', $post_id, $meta_key, $meta_value, $unique);
}

Связанные Функции

Ещё из раздела

Смотрите также: Функции WordPress и Теги Шаблона.