Update User Guide

Author: sclubricants

user_guide_src/source/changelogs/v4.3.0.rst

@@ -45,6 +45,7 @@ Others
 - ``RouteCollection::resetRoutes()`` resets Auto-Discovery of Routes. Previously once discovered, RouteCollection never discover Routes files again even if ``RouteCollection::resetRoutes()`` is called.
 - ``CITestStreamFilter::$buffer = ''`` no longer causes the filter to be registered to listen for streams. Now there
   is a ``CITestStreamFilter::registration()`` method for this. See :ref:`upgrade-430-stream-filter` for details.
+- The second parameter ``$index`` of ``BaseBuilder::updateBatch()`` has changed to ``$constraints``. It now accepts an array, string, or ``RawSql``.
 
 Method Signature Changes
 ========================

user_guide_src/source/database/query_builder.rst

@@ -1608,19 +1608,45 @@ Class Reference
 
         Compiles and executes an ``UPDATE`` statement.
 
-    .. php:method:: updateBatch([$set = null[, $value = null[, $batch_size = 100]]])
+    .. php:method:: updateBatch([$set = null[, $constraints = null[, $batchSize = 100]]])
 
         :param array $set: Field name, or an associative array of field/value pairs
-        :param string $value: Field value, if $set is a single field
-        :param int $batch_size: Count of conditions to group in a single query
+        :param mixed $constraints: The field or fields used as keys to update on.
+        :param int $batchSize: Count of conditions to group in a single query
         :returns:   Number of rows updated or ``false`` on failure
         :rtype:     int|false
 
         Compiles and executes batch ``UPDATE`` statements.
 
-        .. note:: When more than ``$batch_size`` field/value pairs are provided,
-            multiple queries will be executed, each handling up to
-            ``$batch_size`` field/value pairs.
+        .. note:: Set ``$batchSize`` to 0 for unlimited. ``$constraints`` takes a comma delimited string of columns, and array, associative array, or RawSql.
+
+    .. php:method:: updateFields($set, [$addToDefault = false, [$ignore = null]])
+
+        :param mixed $set: Row of columns or array of rows, a row is an array or object
+        :param bool $addToDefault: Adds an additional column than those in dataset
+        :param bool $ignore: An array of columns to ignore from those in $set
+        :returns:   ``BaseBuilder`` instance (method chaining)
+        :rtype:     ``BaseBuilder``
+
+        Used with ``updateBatch()`` and ``upsertBatch()`` methods. This defines the fields which will be updated.
+
+    .. php:method:: onConstraint($set)
+
+        :param mixed $set: A set of fields or field used has keys or constraints
+        :returns:   ``BaseBuilder`` instance (method chaining)
+        :rtype:     ``BaseBuilder``
+
+        Used with ``updateBatch()`` and ``upsertBatch()`` methods. This takes a comma delimited string of columns, and array, associative array, or RawSql.
+
+    .. php:method:: setData($set, [$escape = null, [$alias = '']])
+
+        :param mixed $set: Row of columns or array of rows, a row is an array or object
+        :param bool $escape: Whether to escape values
+        :param bool $alias: A table alias for dataset
+        :returns:   ``BaseBuilder`` instance (method chaining)
+        :rtype:     ``BaseBuilder``
+
+        Used for ``*Batch()`` methods to set data for insert, update, upsert.
 
     .. php:method:: setUpdateBatch($key[, $value = ''[, $escape = null]])
 

user_guide_src/source/database/query_builder/092.php

@@ -1,29 +1,57 @@
 <?php
 
+/**
+ * This file is part of CodeIgniter 4 framework.
+ *
+ * (c) CodeIgniter Foundation <[email protected]>
+ *
+ * For the full copyright and license information, please view
+ * the LICENSE file that was distributed with this source code.
+ */
+
 $data = [
     [
-        'title' => 'Title 1',
-        'name'  => 'Name 1',
-        'date'  => 'Date 1',
+        'title'  => 'Title 1',
+        'author' => 'Author 1',
+        'name'   => 'Name 1',
+        'date'   => 'Date 1',
     ],
     [
-        'title' => 'Title 2',
-        'name'  => 'Name 2',
-        'date'  => 'Date 2',
+        'title'  => 'Title 2',
+        'author' => 'Author 2',
+        'name'   => 'Name 2',
+        'date'   => 'Date 2',
     ],
 ];
 
-$builder->updateBatch($data, 'title');
+$builder->updateBatch($data, ['title', 'author']);
+
+// OR
+$builder->setData($data)->onConstraint('title, author')->updateBatch();
+
+// OR
+$builder->setData($data)
+    ->setAlias('u')
+    ->onConstraint(['`mytable`.`title`' => '`u`.`title`', 'author' => new RawSql('`u`.`author`')])
+    ->updateBatch();
+
+// OR
+$builder->setData($data)
+    ->setAlias('u')
+    ->onConstraint(new RawSql('`mytable`.`title` = `u`.`title` AND `mytable`.`author` = `u`.`author`'))
+    ->updateFields(['last_update' => new RawSql('CURRENT_TIMESTAMP()')], true)
+    ->updateBatch();
 /*
  * Produces:
  * UPDATE `mytable`
  * INNER JOIN (
- * SELECT 'Title 1' `title`, 'Name 1' `name`, 'Date 1' `date` UNION ALL
- * SELECT 'Title 2' `title`, 'Name 2' `name`, 'Date 2' `date`
- * ) u
- * ON `mytable`.`title` = u.`title`
+ * SELECT 'Title 1' `title`, 'Author 1' `author`, 'Name 1' `name`, 'Date 1' `date` UNION ALL
+ * SELECT 'Title 2' `title`, 'Author 2' `author`, 'Name 2' `name`, 'Date 2' `date`
+ * ) `u`
+ * ON `mytable`.`title` = `u`.`title` AND `mytable`.`author` = `u`.`author`
  * SET
- * `mytable`.`title` = u.`title`,
- * `mytable`.`name` = u.`name`,
- * `mytable`.`date` = u.`date`
+ * `mytable`.`title` = `u`.`title`,
+ * `mytable`.`name` = `u`.`name`,
+ * `mytable`.`date` = `u`.`date`,
+ * `mytable`.`last_update` = CURRENT_TIMESTAMP() // this only applies to the last scenario
  */

user_guide_src/source/installation/upgrade_430.rst

@@ -128,6 +128,7 @@ Breaking Enhancements
 - Since the launch of Spark Commands was extracted from ``CodeIgniter\CodeIgniter``, there may be problems running these commands if the ``Services::codeigniter()`` service has been overridden.
 - The return type of ``CodeIgniter\Database\Database::loadForge()`` has been changed to ``Forge``. Extending classes should likewise change the type.
 - The return type of ``CodeIgniter\Database\Database::loadUtils()`` has been changed to ``BaseUtils``. Extending classes should likewise change the type.
+- The second parameter ``$index`` of ``BaseBuilder::updateBatch()`` has changed to ``$constraints``. It now accepts types array, string, or ``RawSql``. Extending classes should likewise change types.
 
 Project Files
 *************