Move user guide and move test to live

Author: sclubricants

tests/system/Database/BaseConnectionTest.php

@@ -165,20 +165,6 @@ public function testMagicGetMissing()
         $this->assertNull($db->foobar);
     }
 
-    public function testEscape()
-    {
-        $db = new MockConnection($this->options);
-
-        $stringArray = [' A simple string ', new RawSql('CURRENT_TIMESTAMP()'), false, null];
-
-        $escapedString = $db->escape($stringArray);
-
-        $this->assertSame("' A simple string '", $escapedString[0]);
-        $this->assertSame('CURRENT_TIMESTAMP()', $escapedString[1]);
-        $this->assertSame(0, $escapedString[2]);
-        $this->assertSame('NULL', $escapedString[3]);
-    }
-
     /**
      * These tests are intended to confirm the current behavior.
      * We do not know if all of these are the correct behavior.

tests/system/Database/Live/EscapeTest.php

@@ -11,6 +11,7 @@
 
 namespace CodeIgniter\Database\Live;
 
+use CodeIgniter\Database\RawSql;
 use CodeIgniter\Test\CIUnitTestCase;
 use CodeIgniter\Test\DatabaseTestTrait;
 
@@ -78,4 +79,22 @@ public function testEscapeLikeStringDirect()
             $this->expectNotToPerformAssertions();
         }
     }
+
+    public function testEscapeStringArray()
+    {
+        $stringArray = [' A simple string ', new RawSql('CURRENT_TIMESTAMP()'), false, null];
+
+        $escapedString = $this->db->escape($stringArray);
+
+        $this->assertSame("' A simple string '", $escapedString[0]);
+        $this->assertSame('CURRENT_TIMESTAMP()', $escapedString[1]);
+
+        if ($this->db->DBDriver === 'Postgre') {
+            $this->assertSame('FALSE', $escapedString[2]);
+        } else {
+            $this->assertSame(0, $escapedString[2]);
+        }
+
+        $this->assertSame('NULL', $escapedString[3]);
+    }
 }

user_guide_src/source/changelogs/v4.3.0.rst

@@ -43,6 +43,7 @@ Enhancements
 - Added ``spark filter:check`` command to check the filters for a route. See :ref:`Controller Filters <spark-filter-check>` for the details.
 - Now **Encryption** can decrypt data encrypted with CI3's Encryption. See :ref:`encryption-compatible-with-ci3`.
 - Now ``spark routes`` command shows route names. See :ref:`URI Routing <routing-spark-routes>`.
+- ``BaseConnection::escape()`` now excludes the ``RawSql`` data type. This allows passing SQL strings into data. See :ref:`database-queries-db-escape`.
 
 Changes
 *******

user_guide_src/source/database/call_function.rst

@@ -37,18 +37,3 @@ database result ID. The connection ID can be accessed using:
 The result ID can be accessed from within your result object, like this:
 
 .. literalinclude:: call_function/004.php
-
-$db->escape();
-============================
-
-This function enables you to escape a string for database calls. The method
-is used by ``BaseBuilder`` for many built in functions. It accepts a string,
-array, object or ``CodeIgniter\Database\RawSql``. When ``RawSql`` is used
-the string is not escaped. This allows you to call SQL functions and
-constants.
-
-.. literalinclude:: call_function/005.php
-
-Here is an example using methods such as ``insert()`` to pass a SQL function.
-
-.. literalinclude:: call_function/006.php

user_guide_src/source/database/call_function/005.php

@@ -102,12 +102,17 @@ this:
 1. $db->escape()
 ================
 
-This function determines the data type so
-that it can escape only string data. It also automatically adds
-single quotes around the data so you don't have to:
+This function determines the data type so that it can escape only string
+data. It also automatically adds single quotes around the data so you
+don't have to:
 
 .. literalinclude:: queries/009.php
 
+When ``RawSql`` is used the string is not escaped. This allows you to call
+SQL functions and constants:
+
+.. literalinclude:: queries/030.php
+
 2. $db->escapeString()
 ======================
 

user_guide_src/source/database/queries.rst

@@ -1,10 +1,15 @@
 <?php
 
-$data = [
-    'title' => 'My title',
-    'name'  => 'My Name',
-    'date'  => 'My date',
-];
+    $data = [
+        'id'          => new RawSql('DEFAULT'),
+        'title'       => 'My title',
+        'name'        => 'My Name',
+        'date'        => '2022-01-01',
+        'last_update' => new RawSql('CURRENT_TIMESTAMP()'),
+    ];
 
-$builder->insert($data);
-// Produces: INSERT INTO mytable (title, name, date) VALUES ('My title', 'My name', 'My date')
+    $builder->insert($data);
+    /* Produces:
+        INSERT INTO mytable (id, title, name, date, last_update)
+        VALUES (DEFAULT, 'My title', 'My name', '2022-01-01', CURRENT_TIMESTAMP())
+    */