wpdb::update()publicWP 2.5.0

Updates the specified data in the specified row of the DB table.

The method includes protection against SQL injections and the data can be passed as is, for example: $_GET['foo'].

Does NOT insert data if it is not in the database - only updates existing data.

Method of the class: wpdb{}

No Hooks.

Return

Int|false.

  • integer — how many rows were processed.
  • 0 — the query was executed correctly, but no one row was processed. If there is already data in the database and you are trying to update it by specifying exactly the same data then wpdb::update() will return 0.
  • false — the query failed or there is an error in the query.

Checking the result of the query for an error should be done by checking the type of the returned data $res === false, because 0 is returned if no fields were updated, but the request was executed correctly.

Usage

global $wpdb;
$wpdb->update( $table, $data, $where, $format, $where_format );
$table(string) (required)
The name of the table where the data needs to be updated.
$data(array) (required)

Data to be updated. The format is: [ 'column_name' => 'new value' ].

If you specify NULL in the value, the value will be set to NULL, the corresponding format is ignored in this case.

$where(array) (required)
A named array of WHERE clauses (in [ column => value ] pairs ).
Multiple clauses will be joined with ANDs.
Both $where columns and $where values should be "raw".
Sending a null value will create an IS NULL comparison - the corresponding format will be ignored in this case.
$format(array|string)

An array of formats to be mapped to each of the values in $data parameter.
If string is specified, than format will be used for all of the items in $data parameter.
When specifying the format, WordPress translates the passed data into the specified format before creating the query. Possible formats:

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

If omitted, all values in $where will be treated as strings. The default format is controlled by wpdb::$field_types property.
Default: null

$where_format(массив/строка)
The same as $format parameter, but for $where data.
Default: null

Examples

0

#1 Update the raw whose ID is 1

The value of the first column is a string, the value of the second column is a number:

$wpdb->update( 'table_name',
	[ 'column1' => 'value1', 'column2' => $_GET['val'] ],
	[ 'ID' => 1 ]
);
0

#2 The same but with specifying the types of passed data

$wpdb->update( 'table',
	[ 'column1' => 'value1', 'column2' => $_GET['val'] ],
	[ 'ID' => 1 ],
	[ '%s', '%d' ],
	[ '%d' ]
);
0

#3 Demo

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

Notes

Changelog

Since 2.5.0 Introduced.

wpdb::update() code WP 6.4.3

public function update( $table, $data, $where, $format = null, $where_format = null ) {
	if ( ! is_array( $data ) || ! is_array( $where ) ) {
		return false;
	}

	$data = $this->process_fields( $table, $data, $format );
	if ( false === $data ) {
		return false;
	}
	$where = $this->process_fields( $table, $where, $where_format );
	if ( false === $where ) {
		return false;
	}

	$fields     = array();
	$conditions = array();
	$values     = array();
	foreach ( $data as $field => $value ) {
		if ( is_null( $value['value'] ) ) {
			$fields[] = "`$field` = NULL";
			continue;
		}

		$fields[] = "`$field` = " . $value['format'];
		$values[] = $value['value'];
	}
	foreach ( $where as $field => $value ) {
		if ( is_null( $value['value'] ) ) {
			$conditions[] = "`$field` IS NULL";
			continue;
		}

		$conditions[] = "`$field` = " . $value['format'];
		$values[]     = $value['value'];
	}

	$fields     = implode( ', ', $fields );
	$conditions = implode( ' AND ', $conditions );

	$sql = "UPDATE `$table` SET $fields WHERE $conditions";

	$this->check_current_query = false;
	return $this->query( $this->prepare( $sql, $values ) );
}