update_post_meta

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

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

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

Функция ожидает экранированную строку. Т.е. перед записью в базу данных значение произвольных полей обрабатываются функцией stripslashes(). Подробнее см.ниже: Экранирование в значениях произвольных полей.
✈ 1 раз = 0.001327с = очень медленно | 50000 раз = 42.23с = очень медленно PHP 7.0.8, WP 4.6.1

Хуков нет.

Возвращает

true в случае успешной операции или false, если произошла ошибка. 
Возвращает true, только если удалось обновить поле, т.е. функция вернет false, если в $meta_value указано старое значение.

Использование

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' );

Еще примеры можно посмотреть <a href=”/function/get_post_meta#usage”>здесь</a>.

Экранирование в значениях произвольных полей

Перед записью в базу данных значение произвольных полей обрабатываются функцией stripslashes(), поэтому нужно быть аккуратным, когда в значениях передаются данные с обратным слэш (), например JSON строка.

Не размещайте экранированные значения

Пример, как делать не следует

Предположим нам нужно разместить в значении произвольного поля такую JSON строку: {“key”:”value with “escaped quotes””}:

$escaped_json = '{"key":"value with \"escaped quotes\""}';
update_post_meta( $id, 'escaped_json', $escaped_json );
$broken = get_post_meta( $id, 'escaped_json', true );

/*
Параметр $broken после обработки stripslashes(), превратиться в нерабочую строку:
{"key":"value with "escaped quotes""}
*/
Пример, как правильно

Добавив еще один уровень экранирования (), с помощью функции wp_slash() (с версии 3.6), вы можете компенсировать обработку stripslashes():

$escaped_json = '{"key":"value with \"escaped quotes\""}';
update_post_meta( $id, 'double_escaped_json', wp_slash($escaped_json) );
$fixed = get_post_meta( $id, 'double_escaped_json', true );
/*
Параметр $fixed после обработки stripslashes(), останется правильным:
{"key":"value with "escaped quotes""}
*/

Код из


wp-includes/post.php

WP 4.7.2

<?php
function update_post_meta( $post_id, $meta_key, $meta_value, $prev_value = '' ) {
	// Make sure meta is added to the post, not a revision.
	if ( $the_post = wp_is_post_revision($post_id) )
		$post_id = $the_post;

	return update_metadata('post', $post_id, $meta_key, $meta_value, $prev_value);
}