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

Update a row in the table

Contents

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

See also See also

Top ↑

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

Expand full source code Collapse full source code View on Trac

Top ↑

Changelog Changelog

Changelog
Version Description
2.5.0 Introduced.

Top ↑

Top ↑

Uses Uses

Uses
Uses Description
wp-includes/wp-db.php: wpdb::process_fields()

Processes arrays of field/value pairs and field formats.
wp-includes/wp-db.php: wpdb::query()

Perform a MySQL database query, using current database connection.
wp-includes/wp-db.php: wpdb::prepare()

Prepares a SQL query for safe execution. Uses sprintf()-like syntax.

Top ↑

Used By Used By

Used By
Used By Description
wp-includes/ms-site.php: wp_update_site()

Updates a site in the database.
wp-includes/comment.php: wp_comments_personal_data_eraser()

Erases personal data associated with an email address from the comments table.
wp-includes/class-wp-customize-manager.php: WP_Customize_Manager::trash_changeset_post()

Trash or delete a changeset post.
wp-includes/theme.php: _wp_keep_alive_customize_changeset_dependent_auto_drafts()

Make sure that auto-draft posts get their post_date bumped or status changed to draft to prevent premature garbage-collection.
wp-includes/class-wp-customize-manager.php: WP_Customize_Manager::_publish_changeset_values()

Publish changeset values.
wp-includes/post.php: wp_add_trashed_suffix_to_post_name_for_post()

Adds a trashed suffix for a given post.
wp-includes/option.php: update_network_option()

Update the value of a network option that was already added.
wp-includes/ms-deprecated.php: update_user_status()

Update the status of a user in the database.
wp-admin/includes/upgrade.php: wp_install_defaults()

Creates the initial content for a newly-installed site.
wp-admin/includes/user.php: wp_delete_user()

Remove user and optionally reassign posts and links to another user.
wp-admin/includes/bookmark.php: wp_insert_link()

Inserts/updates links into/in the database.
wp-admin/includes/class-wp-posts-list-table.php: WP_Posts_List_Table::_display_rows_hierarchical()
wp-includes/pluggable.php: wp_set_password()

Updates the user’s password with a new encrypted one.
wp-includes/deprecated.php: update_usermeta()

Update metadata of user.
wp-includes/taxonomy.php: _update_post_term_count()

Will update term count based on object types of the current taxonomy.
wp-includes/taxonomy.php: _update_generic_term_count()

Will update term count based on number of objects.
wp-includes/taxonomy.php: wp_update_term()

Update term based on arguments provided.
wp-includes/taxonomy.php: wp_insert_term()

Add a new term to the database.
wp-includes/taxonomy.php: wp_delete_term()

Removes a term from the database.
wp-includes/option.php: update_option()

Update the value of an option that was already added.
wp-includes/user.php: wp_insert_user()

Insert a user into the database.
wp-includes/post.php: _transition_post_status()

Hook for managing future post transitions to published.
wp-includes/post.php: wp_publish_post()

Publish a post by transitioning the post status.
wp-includes/post.php: add_ping()

Add a URL to those already pinged.
wp-includes/post.php: wp_insert_post()

Insert or update a post.
wp-includes/post.php: wp_delete_post()

Trash or delete a post or page.
wp-includes/post.php: wp_trash_post_comments()

Moves comments for a post to the trash.
wp-includes/post.php: set_post_type()

Update the post type for the post ID.
wp-includes/revision.php: _wp_upgrade_revisions_of_post()

Upgrade the revisions author, add the current post as a revision and set the revisions version to 1
wp-includes/ms-functions.php: global_terms()

Maintains a canonical list of terms by syncing terms created for each blog with the global terms table.
wp-includes/ms-functions.php: wpmu_activate_signup()

Activate a signup.
wp-includes/class-wp-xmlrpc-server.php: wp_xmlrpc_server::attach_uploads()

Attach upload to a post.
wp-includes/comment.php: wp_set_comment_status()

Sets the status of a comment.
wp-includes/comment.php: wp_update_comment()

Updates an existing comment in the database.
wp-includes/comment.php: wp_update_comment_count_now()

Updates the comment count for the post.
wp-includes/comment.php: do_trackbacks()

Perform trackbacks.
wp-includes/comment.php: wp_delete_comment()

Trashes or deletes a comment.
wp-includes/meta.php: update_metadata_by_mid()

Update meta data by meta ID
wp-includes/meta.php: update_metadata()

Update metadata for the specified object. If no value already exists for the specified object ID and metadata key, the metadata will be added.
Show 34 more used by Hide more used by

Top ↑

User Contributed Notes User Contributed Notes

  1. Skip to note 1 content
    You must log in to vote on the helpfulness of this noteVote results for this note: 10You must log in to vote on the helpfulness of this note
    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
    You must log in to vote on the helpfulness of this noteVote results for this note: 0You must log in to vote on the helpfulness of this note
    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.