1. Getting Started
      1. Basic Installation
      2. What is MODx
    2. Content Editing
      1. Editing Documents
      2. MODx Tags
        1. Document Variables
      3. Terminology
      4. The Manager
      5. Who Should Read This
    3. Designing
      1. Adding Chunks
      2. Adding MODx Tags
        1. Resource Fields
      3. Adding Snippets
      4. Document Caching
      5. Template Basics
    4. Administration
      1. Friendly URL Solutions
      2. Manager Users
        1. Manager Roles And Groups
        2. Reset your Password - Unblock your User
        3. Why Manager Users, Roles and Groups
      3. Moving Site
      4. Taking sites down for maintenance
      5. Upgrading
      6. Web Users
        1. Creating a Web User
        2. Web User Groups and Document Groups
        3. Why Web Users and Groups
    5. Developer's Guide
      1. API Reference
        1. DBAPI
          1. delete
          2. escape
          3. getInsertId
          4. query
          5. select
          6. update
        2. Document Object
        3. DocumentParser Object
          1. addEventListener
          2. changeWebUserPassword
          3. documentContent
          4. documentGenerated
          5. documentIdentifier
          6. documentListing
          7. documentMethod
          8. documentObject
          9. getAllChildren
          10. getCachePath
          11. getChildIds
          12. getDocumentChildren
          13. getDocumentChildrenTVarOutput
          14. getDocumentChildrenTVars
          15. getLoginUserID
          16. getLoginUserName
          17. getLoginUserType
          18. getManagerPath
          19. getParent
          20. getParentIds
          21. getUserData
          22. hasPermission
          23. isBackend
          24. isFrontend
          25. logEvent
          26. maxParserPasses
          27. minParserPasses
          28. regClientCSS
          29. runSnippet
          30. table_prefix
          31. tstart
          32. webAlert
      2. Chunks
      3. Modules
        1. How to create and run a module from within the Content Manager
        2. Managing module dependencies
        3. Setting up configuration parameters
        4. Writing the module code
      4. Plugins
      5. Snippets
      6. Template Variables
        1. (at) Binding
          1. (at)CHUNK
          2. (at)DIRECTORY
          3. (at)DOCUMENT
          4. (at)EVAL
          5. (at)FILE
          6. (at)INHERIT
          7. (at)SELECT
          8. What are (at) Bindings
        2. Creating a Template Variable
        3. What are Template Variables
        4. Widgets
          1. Misc. Widget
          2. DataGrid Widget
          3. Floater Widget
          4. Hyperlink Widget
          5. Marquee Widget
          6. RichTextBox Widget
          7. Ticker Widget
          8. Viewport Widget
          9. What are Widgets

update

Last edited by JP DeVries on Aug 9, 2013.

Welcome to the MODX Documentation. It is an ongoing effort of the MODX community. If you would like to participate or if you notice any errors or missing content, please let us know.

API:DB:update

API Quick reference
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.

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