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

Update a row in the table


Description Description

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’ ) )


Parameters 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 value: 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 value: null


Top ↑

Return Return

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


Top ↑

Source Source

File: wp-includes/wp-db.php

	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 = $conditions = $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

Changelog
Version Description
2.5.0 Introduced.


Top ↑

User Contributed Notes User Contributed Notes

  1. Skip to note 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.
    }
    

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