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.6.2
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 ); }