update_post_meta()
Обновляет указанное произвольное поле (метаполе) указанной записи (поста) или добавляет новое.
Функция может быть использована вместо add_post_meta(), т.к. сначала проверяется существование произвольного поля у указанного поста, если поле не найдено, то управление полностью передается функции add_post_meta().
Если в значение $meta_value передать массив, то он автоматически будет записан в виде сериализованной строки, т.е. нет необходимости обрабатывать массив функцией serialize() перед передачей его в значение $meta_value.
ВАЖНО! Функция проверяет не является ли указанная запись (ID поста) ревизией. Если указана ревизия, то ID меняется на ID родительской записи. Т.е. метаданные в любом случае будут обновляться у родительской записи (не у ревизии).
ВАЖНО! Функция ожидает экранированную строку в параметрах $meta_key и $meta_value. Т.е. перед записью в базу данных значение произвольных полей обрабатываются функцией wp_unslash(). Подробнее смотрите: «Экранирование в значениях произвольных полей».
Хуков нет.
Возвращает
int|true|false.
true- при успешном обновлении.false- при неудаче. Или когда было передано такое же значение поля (как в бд).Число- ID первичного поля таблицы метаполей (meta_id), когда было создано новое поле.
Использование
update_post_meta( $post_id, $meta_key, $meta_value, $prev_value );
- $post_id(число) (обязательный)
- ID поста, произвольное поле которого нужно обновить/создать.
- $meta_key(строка) (обязательный)
- Ключ произвольного поля, которое нужно обновить/создать.
- $meta_value(строка/массив) (обязательный)
- Новое, значение произвольного поля, которое нужно обновить/создать. Если передать массив, то значение будет серриализованно в строку.
- $prev_value(строка/массив)
- Значение произвольного поля, которое мы хотим изменить. Нужно для тех случаев, когда у поста имеются несколько произвольных полей с одинаковыми ключами. Если не указать этот параметр и у поста имеются несколько полей с одинаковыми ключами, то все поля будут обновлены.
По умолчанию: ''
Примеры
#1 Обновим произвольное поле my_key, у поста 76
Заменим имеющееся там значение на Steve:
update_post_meta( 76, 'my_key', 'Steve' );
#2 Примеры операций над полями
Предположим, что у поста 76 есть 4 следующих произвольных поля, со значениями:
key_1 = Happy key_1 = Sad key_2 = Gregory my_key = Steve
Изменим значение поля key_2 на Hans:
update_post_meta( 76, 'key_2', 'Hans' );
Изменим значение поля key_1 с Sad на Happy:
update_post_meta( 76, 'key_1', 'Happy', 'Sad' );
Теперь, у нас такие поля:
key_1 = Happy key_1 = Happy key_2 = Hans my_key = Steve
Изменим значение первого поля key_1 с Happy на Excited:
update_post_meta( 76, 'key_1', 'Excited', 'Happy' ); // Или update_post_meta( 76, 'key_1', 'Excited' ); // Такое использование, обновит только первое поле (всего одно)! // Чтобы обновить все поля с ключом "key_1" на Excited, нужно применить функцию к каждому полю, например через цикл: $key1_values = get_post_custom_values( 'key_1', 76 ); foreach ( $key1_values as $value ) update_post_meta( 76, 'key_1', 'Excited', $value );
#3 Изменим файл шаблона постоянной страницы.
Файл шаблона для постоянной страницы записывается в системное произвольное поле _wp_page_template:
update_post_meta( $id, '_wp_page_template', 'new_template.php' );
#4 Еще примеры
Список изменений
| С версии 1.5.0 | Введена. |
Код update_post_meta() update post meta WP 6.7.1
function update_post_meta( $post_id, $meta_key, $meta_value, $prev_value = '' ) {
// Make sure meta is updated for the post, not for a revision.
$the_post = wp_is_post_revision( $post_id );
if ( $the_post ) {
$post_id = $the_post;
}
return update_metadata( 'post', $post_id, $meta_key, $meta_value, $prev_value );
}