wpdb::insert() │ public │ WP 2.5.0

Inserts a row (the specified data) into the specified table.

The method cleans the passed data and protects against SQL injections, so the data can be "dirty" (uncleaned), for example: $_GET['foo'].

If a post with the same unique key already exists, the data will not be updated. To update, use wpdb::update() or wpdb::replace().

After adding data, the created AUTO_INCREMENT value can be obtained in the variable: $wpdb->insert_id. If data insertion fails, $wpdb->insert_id will be equal to 0.

Method of the class: wpdb{}

Uses: wpdb::_insert_replace_helper()

No Hooks.

Returns

Int|false.

  • number — the number of inserted rows.
  • false — if the data was not inserted into the table.

WARNING! Will return false (without any errors) when the string being passed for insertion (cell value) is longer than the maximum allowed. For example, a column varchar(10) (value length 10 characters), but the passed data for insertion specifies a string with 11 or more characters.

Catching such a bug is very difficult! Therefore, it should be kept in mind when everything seems to be working (correct data is being passed), but wpdb::insert() returns false without any errors.

This issue affects almost all methods, including:
wpdb::replace()
wpdb::insert()
wpdb::update()
wpdb::delete()

Usage

global $wpdb;
$wpdb->insert( $table, $data, $format );
$table(string) (required)
The name of the table into which we will insert data.
$data(array)

The data to be inserted. Each element of the array looks like this: [ 'table column' => 'value' ].

If NULL is specified in the value, then the value will be set to NULL, and the specified format will be ignored.

The passed data MUST NOT be cleaned: esc_sql().

$format(array/string)

An array of data formats that will be associated with the specified values in the $data parameter. If a string is specified, it (the format) will be associated with all data. When specifying a format, WordPress converts the passed data to the specified format before saving the data. Possible formats:

  • %s - string
  • %d - integer
  • %f - float

If not specified, the format string will be used for all values of $data, unless otherwise specified in the property wpdb::$field_types.
Default: null

Examples

3

#1 Getting the ID of the inserted object

To get it, use $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

#2 Insert a line into the database table 

// insert string with values for two fields (values for other fields will be default)
$wpdb->insert( 'table', [ 'column' => 'foo', 'field' => 'bar' ] );

// specifying data types
$wpdb->insert( 'table', [ 'column' => 'foo', 'field' => 1337 ], [ '%s', '%d' ] );

Notes

Changelog

Since 2.5.0 Introduced.

wpdb::insert() code WP 6.9

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

wpdb