wpdb::replace()publicWP 3.0.0

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

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

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

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

Для вставки новой строки необязательно указывать поле с авто-инкрементом. Например, у нас есть таблица с полем id (AUTO_INCREMENT). Можно указать значения всех полей кроме id и строка будет добавлена в таблицу.

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

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

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

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

Всегда заменяются все поля таблицы. Например, если у таблицы есть поля 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

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

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

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

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

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

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

Заметки

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

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

Код wpdb::replace() WP 6.4.3

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