add_post_meta

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

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

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

Хуков нет.

Возвращает

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 и это поле не будет выводится в админке на странице редактирования постов/постоянных страниц.

Код из


wp-includes/post.php

WP 4.7.2

<?php
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);
}