Функция add_post_meta() в WordPress

Функция add_post_meta() используется, чтобы добавить мета-поля к определённому сообщению. Мета-поля — это дополнительные данные, которые не входят в стандартные поля сообщения, такие как заголовок и содержимое. Эти поля могут быть использованы для хранения другой информации, связанной с сообщением.

Как работает add_post_meta()

Функция позволяет добавлять мета-поля, когда несколько полей с одинаковыми ключами используются. У функции есть параметр $unique, который по умолчанию установлен в false. Это означает, что можно создавать несколько полей с одинаковыми ключами.

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

Важно!

1. Функция проверяет, что указанный ID сообщения не является ревизией. Если указан ID ревизии, он будет заменён на ID основного сообщения. Это значит, что метаданные всегда добавляются к основному сообщению, а не к его ревизиям.

2. Функция ожидает строки, обрабатываемые функцией wp_unslash() для параметров $meta_key и $meta_value перед вставкой в базу данных.

Как добавить мета-поля

Мета-поля называются "Пользовательские поля" на экране управления WordPress.

Синтаксис

add_post_meta( $post_id, $meta_key, $meta_value, $unique );

• $post_id (int, обязательный) — ID сообщения, к которому добавляется мета-поле.
• $meta_key (string, обязательный) — имя (ключ) мета-поля.
• $meta_value (mixed, обязательный) — значение мета-поля.
• $unique (bool) — определяет, добавлять ли тот же ключ несколько раз:
  • true — уникально (только одно);
  • false — не уникально (можно добавлять несколько полей с одним ключом).

По умолчанию этот параметр установлен в false.

Примеры использования

Пример 1: Создание скрытого пользовательского поля

Если вам нужно создать пользовательское поле, которое будет невидимо для пользователей, используйте ключ, начинающийся с "_" (нижнего подчеркивания):

add_post_meta( 68, '_color', 'red', true );

В этом примере добавляется уникальное поле "_color" с значением "red", которое не будет отображаться на странице редактирования сообщения.

Пример 2: Добавление поля только если его еще нет

Чтобы быть уверенным, что поле с ключом "my_key" не существует, перед добавлением можно использовать:

add_post_meta( 68, 'my_key', '47', true );

Пример 3: Основное использование

Добавим пользовательское поле "my_key" со значением 47 к сообщению с ID 68:

add_post_meta( 68, 'my_key', 47 );

Пример 4: Добавить или обновить уникальное метаполе

Добавьте метаполе, если его ещё нет, или обновите существующее. Если параметр $unique установлен в true, поле не будет обновлено, если оно уже существует.

if ( !update_post_meta(7, 'fruit', 'banana') ) {
    add_post_meta(7, 'fruit', 'banana', true);
}

Пример 5: Добавление нескольких полей с одинаковыми ключами

Можно добавлять несколько мета-полей с одним и тем же ключом:

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

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

Функция возвращает:

• int — ID мета-поля в случае успеха;
• false — в случае ошибки.

Изменения

Функция add_post_meta() была введена в версии WordPress 1.5.0.

Код функции

Вот общий вид кода функции add_post_meta():

function add_post_meta( $post_id, $meta_key, $meta_value, $unique = false ) {
// Убедимся, что мета добавляется к сообщению, а не к его ревизии.
$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 );

}

Эта простая функция делает добавление мета данных к сообщениям в WordPress лёгким и удобным для разработчиков.