add_post_meta()

Функция добавляет мета-поле (произвольное поле) для поста (записи, страницы или поста произвольного типа) с указанным ID.

Возвращает ID метаданных в случае их добавления, либо false, если они добавлены не были.

Обратите внимание, что если мета-поле с указанным ключом уже существует у поста, то функция добавит ещё одно поле с таким ключом (если только вы не указали параметр $unique в значение true, тогда и вовсе ничего не произойдёт, если поле уже существует). Поэтому, если вдруг вы хотите изменить значение уже существующего мета-поля, то вам нужна update_post_meta().

add_post_meta( $post_id, $meta_key, $meta_value, $unique = false )

Параметры

$post_id: (целое число) ID поста. Если вы передали ID редакции, то будет использовать ID оригинального поста.
$meta_key: (строка) Ключ произвольного поля.
$meta_value: Добавляемое значение.

Функция обезопасивает значение для использования в SQL-запросе в базу данных, поэтому об этом можете не беспокоиться. Но очистка значения в зависимости от передаваемых данных всё же рекомендуется. Кроме того, если вдруг вы передатите нескалярное значение в функцию, например массив, то она его сериализует.
$unique: (логическое) Функция позволяет добавлять в БД несколько значений произвольного поля с одним и тем же ключом. Если этот параметр установлен в значение true, то повторные значения для ключа добавляться не будут.

Примеры

Самое базовое использование функции – добавляем метаполе color, но если оно уже существует у поста, то повторное не добавляем.

add_post_meta( 54, 'color', '#ffffff', true );

А теперь добавим несколько метаполей с одним и тем же ключом.

add_post_meta( 1, 'true_key', 'value' );
add_post_meta( 1, 'true_key', '12345' );
add_post_meta( 1, 'true_key', 'Привет, мир!' );
add_post_meta( 1, 'true_key', array( 'post_title' => 'Привет, мир!' ) );