add_post_meta()
Добавляет произвольное поле для указанной записи (поста).
Функцию нужно использовать, когда используются несколько произвольных полей с одинаковыми ключами. Для этого у функции есть параметр $unique (уникальный), который по умолчанию false, т.е. по умолчанию создается не уникальный ключ, т.е. ключей (метаполей) может быть много.
В остальных случаях, для универсальности можно использовать функцию update_post_meta(). Она часто удобнее, потому что одновременно: обновляет поле если оно есть или создает новое, если такого поля нет.
ВАЖНО! Функция проверяет не является ли указанная запись (ID поста) ревизией. Если указана ревизия, то ID меняется на ID родительской записи. Т.е. метаданные в любом случае будут обновляться у родительской записи (не у ревизии).
ВАЖНО! Функция ожидает экранированную строку в параметрах $meta_key и $meta_value. Т.е. перед записью в базу данных значение произвольных полей обрабатываются функцией wp_unslash(). Подробнее смотрите: Экранирование в значениях произвольных полей.
Хуков нет.
Возвращает
int|false.
- true - операция по добавлению поля прошла удачно
- false - поле добавить не удалось
Использование
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:
add_post_meta( 68, 'my_key', 47 );
#2 Добавим поле только если его еще нет
Если мы хотим быть уверены, что поля с ключом "my_key" не существует, перед тем как добавлять его:
add_post_meta( 68, 'my_key', 47, true );
#3 Добавление или обновление уникального произвольного поля
Добавим произвольное поле, если такое поле еще не существует или обновим существующее. Важно понимать, что если четвертый параметр add_post_meta стоит в true, то поле не будет обновлено, если оно уже существует (пример ниже).
add_post_meta( 7, 'fruit', 'banana', true ) or update_post_meta( 7, 'fruit', 'banana' );
для этого нужно использовать такой вариант:
if ( !update_post_meta(...) ) add_post_meta(...) )
#4 Несколько полей с одинаковыми ключами
А вот пример, позволяющий добавить нам несколько произвольных полей с одинаковыми ключами "my_key":
add_post_meta( 68, 'my_key', 47 ); add_post_meta( 68, 'my_key', 682 ); add_post_meta( 68, 'my_key', 'The quick, brown fox jumped over the lazy dog.'); ...
Еще примеры можете посмотреть здесь.
#5 Создание системных (спрятанных) произвольных полей
Если вы разработчик и вам нужно создать произвольное поле, которое не будет видно пользователям, но при этом будет работать как обычное произвольное поле, то знайте что WordPress не показывает произвольные поля начинающиеся с "_" (нижнего подчеркивания). Не показывает значит, что они игнорируются на странице редактирования постов или при использовании функции шаблона the_meta().
Поэтому, если нужно вдруг нужно спрятать произвольное поле, то нужно создавать поле с ключом начинающимся с "_", например:
<?php add_post_meta( 68, '_color', 'red', true ); ?>
добавит уникальное произвольное поле _color со значением red и это поле не будет выводится в админке на странице редактирования постов/постоянных страниц.
Список изменений
| С версии 1.5.0 | Введена. |
Код add_post_meta() add post meta WP 6.5.2
function add_post_meta( $post_id, $meta_key, $meta_value, $unique = false ) {
// Make sure meta is added to the post, not a revision.
$the_post = wp_is_post_revision( $post_id );
if ( $the_post ) {
$post_id = $the_post;
}
return add_metadata( 'post', $post_id, $meta_key, $meta_value, $unique );
}