add_post_meta()
Додає довільне поле для зазначеного запису (поста).
Функцію слід використовувати, коли використовуються кілька довільних полів із однаковими ключами. Для цього функція має параметр $unique (унікальний), який за умовчанням false, тобто. за умовчанням створюється унікальний ключ, тобто. ключів (метаполів) може бути багато.
В інших випадках для універсальності можна використовувати функцію update_post_meta() . Вона часто зручніша, тому що одночасно: оновлює поле якщо воно є або створює нове, якщо такого поля немає.
ВАЖЛИВО! Функція перевіряє, чи не є вказаний запис (ID поста) ревізією. Якщо вказано ревізію, то ID змінюється на ID батьківського запису. Тобто. метадані в будь-якому випадку оновлюватимуться у батьківського запису (не в ревізії).
ВАЖЛИВО! Функція очікує екранований рядок у параметрах $meta_key та $meta_value . Тобто. перед записом до бази даних значення довільних полів обробляються функцією wp_unslash() . Детальніше дивіться: Екранування у значеннях довільних полів .
add_metadata()
Хуків немає.
Повертає
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 Додавання або оновлення унікального довільного поля
Додамо довільне поле, якщо таке поле ще немає або оновимо існуюче. Важливо розуміти, що якщо четвертий параметр add_post_meta стоїть у true, поле не буде оновлено, якщо воно вже існує (приклад нижче).
add_post_meta( 7, 'fruit', 'banana', true ) або update_post_meta( 7, 'fruit', 'banana' );
для цього потрібно використати такий варіант:
if ( !update_post_meta(...) ) add_post_meta(...) )
#3 Додамо поле тільки якщо його ще немає
Якщо ми хочемо бути впевнені, що поля з ключем “my_key” не існує перед тим, як додавати його:
add_post_meta(68, 'my_key', 47, true);
#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.0.2
function add_post_meta( $post_id, $meta_key, $meta_value, $unique = false ) {
// Make sure meta is added to the post, немає 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);
}