update_user_meta() – обновляет значения параметров пользователя

3.0.0 wp-includes / user.php / Кодекс WordPress

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

До версии WordPress 3.0 мы использовали функцию update_usermeta() для этой цели.

Функция возвращает:

true – мета-поле обновлено и изменило своё значение.
false – не обновлено. Например из-за того, что указан несуществующий пользователь или новое значение мета-поля соответствует старому.
ID мета-поля – если его не существовало вообще, а функция его добавила.

update_user_meta( $user_id, $meta_key, $meta_value, $prev_value = '' )

Параметры

$user_id: (целое число) ID пользователя.
$meta_key: (строка) Значение в столбце meta_key в таблице базы данных wp_usermeta, meta_value которого нужно обновить. Иными словами – ключ мета-поля.
$meta_value: Обновляемое значение параметра $meta_key. Если передали массив, то он сериализуется функцией maybe_serialize().
$prev_value: Предыдущее значение параметра. По умолчанию функция обновляет все существующие параметры с указанным ключом, поэтому, указав предыдущее значение, мы можем обновить только тот параметр, который необходимо.

Примеры

1. Основые использования

В отдельном уроке мы добавляли поля в профили пользователей, у нас там было два мета-параметра, город city и пол gender. Попробуем обновить поле с городом для пользователя с ID=1.

$user_id = 1;
 
update_user_meta( $user_id, 'city', 'Милан' );

Попробуем сделать то же самое для текущего пользователя, в этом нам поможет функция get_current_user_id().

update_user_meta( get_current_user_id(), 'city', 'Милан' );

Напоминаю, что если поля city у пользователя не существует вообще, то оно будет добавлено.

2. Работа с параметром $prev_value

Сейчас мы поговорим о ситуациях, когда под одним и тем же ключом у пользователя могут быть несколько значений мета-полей. Например в контексте city мы можем предположить, что там сохраняются города, в которых побывал пользователь.

Допустим, в базе данных это выглядит вот так:

+---------+----------------------+-----------------
| user_id | meta_key             | meta_value                                                                                               |
+---------+----------------------+-----------------
| 152     | city                 | Рим                                         
| 152     | city                 | Берлин                                                       
| 152     | city                 | Осло

И по умолчанию функция update_user_meta() заменит все значения!

То есть после того, как мы используем:

update_user_meta( 152, 'city', 'Братислава' );

То все три значения «Рим», «Берлин» и «Осло» превратятся в Братиславу. Чтобы этого избежать, как раз и указывают третий параметр $prev_value. Допустим хотим поменять Рим на «Братислава», тогда:

update_user_meta( 152, 'city', 'Братислава', 'Рим' );

3. Как проверить, что поле не добавилось/обновилось из-за ошибки?

В самом начале я упоминал, что функция возвращает false, если поле не было обновлено по какой-то причине. Причём причиной может быть как ошибка обновления, так и то, что новое переданное значение совпадает с предыдущим.

Чтобы разделить эти две причины, мы можем использовать код:

$user_id = 1;
$new_value = 'какое-то новое значение';
 
$updated = update_user_meta( $user_id, 'true_meta_key', $new_value );
 
// окей, функция вернула false, но это пока ничего не значит!
if( false == $updated ) {
	// чтобы понять, произошла ли ошибка, попробуем получить значение поля и сравнить его
	if( $new_value != get_user_meta( $user_id, 'true_meta_key', true ) ) {
		wp_die( 'Ошибка обновления поля! Возможно ID пользователя некорректный!' );
	}
}

Миша

Впервые познакомился с WordPress в 2009 году. Организатор и спикер на конференциях WordCamp. Преподаватель в школе Нетология.

Пишите, если нужна помощь с сайтом или разработка с нуля.

Параметры
Примеры