WordPress как на ладони
Недорогой хостинг для сайтов на WordPress: wordpress.jino.ru Авторские Темы для WordPress

wpdb::replace() WP 1.0

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

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

После вставки, ID созданный для колонки AUTO_INCREMENT можно получить в свойстве $wpdb->insert_id.

Метод включает защиту от SQL инъекций и данные можно передавать неочищенные, например: $_GET['foo']...

PRIMARY KEY может состоять из нескольких ключей. В этом случае при поиске для замены или для создания новой строки всегда будут использоваться колонки указанные в PRIMARY KEY. Например PRIMARY KEY состоит из двух колонок ID и type, т.е. ключ при создании указывался так: PRIMARY KEY (ID,type). Тогда для замены существующей строки в $data нужно указать значение этих двух колонок. Если например указать ID и не указать type, то существующая строка не будет найдена и будет создана новая строка с указанным ID и пустым значением type. Все остальные поля кроме полей из PRIMARY KEY в поиске существующей строки не участвуют.

Если длина строки в параметре $data больше чем допускается в ячейке таблицы MySQL, вставка провалиться и функция вернет false. При этом в свойство $wpdb->last_error сообщение об ошибке НЕ будет записано!

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

Всегда заменяются все поля таблицы. Например, если у таблицы есть поля primary, one, two, three, а мы указали в параметре $data только primary, one, то поля two и three получат дефолтные значения, даже если там уже были данные.

{} Это метод класса: wpdb{}

Работает на основе: wpdb::_insert_replace_helper()

Хуков нет.

Возвращает

int|false. Число (кол-во обработанных строк), 0 или false.

  • число - сколько строк было обработано (удалено или вставлено). Если была замена (обновление), то для каждой обновленной строки вернется +2 (удаление и вставка). Если была просто вставка, то для каждой вставленной строки вернется +1.
  • 0 - запрос был выполнен корректно, но ни одна строка не была обработана.
  • false - запрос провалился - ошибка запроса. Или когда невозможно заменить или создать новую строку в таблице.

Вернет количество затронутых строк - это сумма вставленных и удаленных строк. Если вернулось 1 при замене одной строки - это значит что одна строка была вставлена и ни одна не была удалена. Если число больше 1 - это значит, что одна или больше строк были удалены перед вставкой новой строки.

Иногда может произойти замена сразу нескольких старых строк - это когда заменяемые данные совпадают с существующими, а уникальный индекс у старых строк при этом разный.

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

global $wpdb;
$wpdb->replace( $table, $data, $format );
$table(строка) (обязательный)
Название таблицы, в которой нужно заменить данные.
$data(массив) (обязательный)

Данные, которые нужно заменить/вставить в формате [ 'название колонки' => 'новое значение' ].

Если в значении указать NULL, то в значение будет установлено в NULL, соответствующий формат при этом игнорируется.

$format(массив/строка)

Массив форматов данных которые будут ассоциированы с указанными значениями в параметре $data. Если указана строка, то она (формат) будет ассоциирован со всеми данными. При указании формата, WordPress переводит переданные данные в указанный формат перед созданием запроса. Возможные форматы:

  • %s - строка
  • %d - целое число
  • %f - дробное число

Если не указать, то для всех значений $data будет указан формат строка, если иное не указано в свойстве wpdb::$field_types.
По умолчанию: null

Примеры

#1 Заменим строку с главным ключом ID = 1

(подразумевается что таблица состоит из трех колонок ID, column1, column2).

Строка будет добавлена если её нет или полностью обновлена если она есть. Тут важно указывать значения для всех полей, потому что поля без значений получат дефолтные, даже если в них до этого были данные.

$wpdb->replace( 'table_name', [
	'ID'      => 1,
	'column1' => 'value1',
	'column2' => 123
] );

#2 Укажем форматы

$wpdb->replace( 'table', [ 'column' => 'foo', 'field' => 1337 ], [ '%s', '%d' ] );

Заметки

  • Смотрите: wpdb::prepare()
  • Смотрите: wpdb::$field_types
  • Смотрите: wp_set_wpdb_vars()

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

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

Код wpdb::replace() WP 5.7.2

<?php
public function replace( $table, $data, $format = null ) {
	return $this->_insert_replace_helper( $table, $data, $format, 'REPLACE' );
}

Из метки: wpdb

Комментариев нет
    Войти