update_post_meta()WP 1.5.0

Обновляет указанное произвольное поле (метаполе) указанной записи (поста) или добавляет новое.

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

Если в значение $meta_value передать массив, то он автоматически будет записан в виде сериализованной строки, т.е. нет необходимости обрабатывать массив функцией serialize() перед передачей его в значение $meta_value.

ВАЖНО! Функция проверяет не является ли указанная запись (ID поста) ревизией. Если указана ревизия, то ID меняется на ID родительской записи. Т.е. метаданные в любом случае будут обновляться у родительской записи (не у ревизии).

ВАЖНО! Функция ожидает экранированную строку в параметрах $meta_key и $meta_value. Т.е. перед записью в базу данных значение произвольных полей обрабатываются функцией wp_unslash(). Подробнее смотрите: «Экранирование в значениях произвольных полей».

Работает на основе: update_metadata()
1 раз — 0.001327 сек (очень медленно) | 50000 раз — 42.23 сек (очень медленно) | PHP 7.0.8, WP 4.6.1

Хуков нет.

Возвращает

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(строка/массив)
Значение произвольного поля, которое мы хотим изменить. Нужно для тех случаев, когда у поста имеются несколько произвольных полей с одинаковыми ключами. Если не указать этот параметр и у поста имеются несколько полей с одинаковыми ключами, то все поля будут обновлены.
По умолчанию: ''

Примеры

2

#1 Обновим произвольное поле my_key, у поста 76

Заменим имеющееся там значение на Steve:

update_post_meta( 76, 'my_key', 'Steve' );
0

#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 );
0

#3 Изменим файл шаблона постоянной страницы.

Файл шаблона для постоянной страницы записывается в системное произвольное поле _wp_page_template:

update_post_meta( $id, '_wp_page_template', 'new_template.php' );
0

#4 Еще примеры

Смотрите здесь

Список изменений

С версии 1.5.0 Введена.

Код 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 );
}