wpdb::update( string $table, array $data, array $where, array|string $format = null, array|string $where_format = null ): int|false

Updates a row in the table.


Description

Examples:

wpdb::update( 'table', array( 'column' => 'foo', 'field' => 'bar' ), array( 'ID' => 1 ) )
wpdb::update( 'table', array( 'column' => 'foo', 'field' => 1337 ), array( 'ID' => 1 ), array( '%s', '%d' ), array( '%d' ) )

Top ↑

See also


Top ↑

Parameters

$table string Required
Table name.
$data array Required
Data to update (in column => value pairs).
Both $data columns and $data values should be "raw" (neither should be SQL escaped).
Sending a null value will cause the column to 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 Optional
An array of formats to be mapped to each of the values in $data.
If string, that format will be used for all of the values in $data.
A format is one of '%d', '%f', '%s' (integer, float, string).
If omitted, all values in $data will be treated as strings unless otherwise specified in wpdb::$field_types.

Default: null

$where_format array|string Optional
An array of formats to be mapped to each of the values in $where.
If string, that format will be used for all of the items in $where.
A format is one of '%d', '%f', '%s' (integer, float, string).
If omitted, all values in $where will be treated as strings.

Default: null


Top ↑

Return

int|false The number of rows updated, or false on error.


Top ↑

Source

File: wp-includes/class-wpdb.php. View all references

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 ) );
}


Top ↑

Changelog

Changelog
Version Description
2.5.0 Introduced.

Top ↑

User Contributed Notes

  1. Skip to note 1 content
    Contributed by J.D. Grimes

    Keep in mind that a return value of 0 doesn’t indicate failure. Nor does it necessarily mean that no matching rows were found: it may be that there were matching rows, but the data didn’t need to be updated because they matched the data already. To check only for database errors you need to use strict equals:

    $updated = $wpdb->update( $table, $data, $where );
    
    if ( false === $updated ) {
        // There was an error.
    } else {
        // No error. You can check updated to see how many rows were changed.
    }
  2. Skip to note 2 content
    Contributed by wp_kc

    Just in case it isn’t clear, as of WordPress v4.4 you can specify NULL data values and/or NULL WHERE clause values as follows. When a value is set to NULL the corresponding format string is ignored.

    $data = [ 'a' => NULL ]; // NULL value.
    $format = [ NULL ];  // Ignored when corresponding data is NULL, set to NULL for readability.
    $where = [ 'id' => NULL ]; // NULL value in WHERE clause.
    $where_format = [ NULL ];  // Ignored when corresponding WHERE data is NULL, set to NULL for readability.
    $wpdb->update( $wpdb->prefix . 'my_table', $data, $where, $format, $where_format );
    $wpdb->update( $wpdb->prefix . 'my_table', $data, $where ); // Also works in this case.

You must log in before being able to contribute a note or feedback.