wpdb::insert() │ public │ WP 2.5.0

Вставляет строку (указанные данные) в указанную таблицу.

Метод очищает переданные данные и защищает от SQL инъекций, поэтому данные могут быть «грязные» (неочищенные), например: $_GET['foo'].

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

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

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

Хуков нет.

Возвращает

int|false.

  • число — число вставленных строк.
  • false — если данные не были вставлены в таблицу.

ВНИМАНИЕ! Вернет false (без каких либо ошибок), когда передаваемая для вставки строка (значение ячейки) длинее максимально возможного. Например колонка varchar(10) (длина значения 10 символов), а в переданных данных для вставки указана строка с 11 или более символами.

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

Такая проблема касается почти всех методов, это:
wpdb::replace()
wpdb::insert()
wpdb::update()
wpdb::delete()

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

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

Данные которые нужно вставить. Каждый элемент массива выглядит так: [ 'колонка таблицы' => 'значение' ].

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

Передаваемые данные НЕ должны быть очищены: esc_sql().

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

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

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

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

Примеры

1

#1 Вставим строку в таблицу БД 

// вставка строки с указанием значений для двух полей (значения для остальных полей будут дефолтные)
$wpdb->insert( 'table', [ 'column' => 'foo', 'field' => 'bar' ] );

// с указанием типов данных
$wpdb->insert( 'table', [ 'column' => 'foo', 'field' => 1337 ], [ '%s', '%d' ] );
1

#2 Получение идентификатора вставленного объекта

Чтобы получить его, используйте $wpdb->insert_id:

global $wpdb;

$table = $wpdb->prefix . 'my_table_name';
$data = [ 'column1' => 'data one', 'column2' => 123 ];

$wpdb->insert( $table, $data );

$my_id = $wpdb->insert_id;

Заметки

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

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

Код wpdb::insert() WP 6.5.2

wp-includes/class-wpdb.php 
public function insert( $table, $data, $format = null ) {
	return $this->_insert_replace_helper( $table, $data, $format, 'INSERT' );
}

wpdb