update
Last edited by JP DeVries on Aug 9, 2013.
API:DB:update
Variable name: | update |
Modx versions: | 0.9.x + Evolution |
Input parameters: | (String $fields, String $table, String $where) |
Return if successful: | true |
Return type: | bool |
Return on failure: | false |
Object parent: | DocumentParser -> DBAPI |
Description
boolean update(String $fields, String $table, String $where)
Updating a value or a group of values in a table is very easy using the DBAPI update function.
This function allows you to update fields in a MySQL database. $fields may be either a simple String, if you're only updating one field in a table, or an associative array consisting of field => new_value to update multiple fields. The $table argument is the actual table in the database you're going to be updating, and if this is empty, the function will return false. The $where argument is the condition under which the table should be updated, and if it's left blank it will update all rows in the table. On failure, this function returns false, and on success, it returns true.
Usage
$rows_affected = $modx->db->update("fields", "table_name" [, "where value"]);
The "fields" argument
The "fields" argument can be an (associative) array if more than one field is to be updated. ie:
$fields = array( "field1" => 1, "field2" => 2, "field3" => "three" ) $rows_affected = $modx->db->update($fields, "table_name", "where value");
Otherwise, it can simply be the field and value you want to update:
$rows_affected = $modx->db->update("field=value" "table_name", "where value");
The "table" argument
The "table" argument is the table to update. You can use the MODx function to return the full tablename; this is probably the best way, since you won't have to remember to include the prefix of the table names for your site:
$table_name = $modx->getFullTableName("table"); $rows_affected = $modx->db->update($fields, $table_name, "where value"); The "where" argument
The "where" argument tells the database the specific record to update:
$rows_affected = $modx->db->update($fields, "table_name", "field = value");
Examples
The following function takes an id and username as parameters and updates the database with a new username, based on the id passed to the function:
function update_username( $id, $username ) { global $modx; $table = $modx->getFullTableName( 'user_table' ); $result = $modx->db->update( 'username = "' . $username . '"', $table, 'userid = "' . $id . '"' ); return $result; // Returns 'true' on success, 'false' on failure. }
This snippet uses an array to update multiple fields in a database:
$table = $modx->getFullTableName( 'cars_table' ); $fields = array('make' => $new_make, 'model' => $new_model, 'color' => $new_color, 'year' => $new_year, 'updated'=> time() ); $result = $modx->db->update( $fields, $table, 'id = "' . $id . '"' ); if( $result ) { echo 'Table updated.'; } else { echo 'Query Failed!'; }
Example 3
$table = $modx->getFullTableName("site_content"); $fields = array( "pagetitle" => "New Title", "alias" => "new-alias", "menuindex" => 2, "published" => 1 ) $rows_affected = $modx->db->update($fields, $table, "id = 45");
will change document 45's title to "New Title", its alias to "new-alias", make it the second item in the menu, and publish it.
Example 4
$table = $modx->getFullTableName("system_settings"); $rows_affected = $modx->db->update("setting_value = '5'", $table, "setting_name='default_template'");
will change the site's default template to template 5.
Related
query(), [getAffectedRows](), escape()
Notes
It's important to note that, if taking any user-inputted data (ie. via a $_GET request), you should always first sanitize the data before using it in a MySQL query. Using the $modx->db->escape() function will escape all potentially harmful characters that could be used to inject an arbitrary command.
Function Source
File: manager/includes/extenders/dbapi.class.inc.php
Line: 185
function update($fields, $table, $where = "") { if (!$table) return false; else { if (!is_array($fields)) $flds = $fields; else { $flds = ''; foreach ($fields as $key => $value) { if (!empty ($flds)) $flds .= ","; $flds .= $key . "="; $flds .= "'" . $value . "'"; } } $where = ($where != "") ? "WHERE $where" : ""; return $this->query("UPDATE $table SET $flds $where"); } }
Suggest an edit to this page on GitHub (Requires GitHub account. Opens a new window/tab).