Add RawSql to BaseConnection->escape()

Author: sclubricants

system/Database/BaseConnection.php

@@ -1238,6 +1238,10 @@ public function escape($str)
         }
 
         if (is_string($str) || (is_object($str) && method_exists($str, '__toString'))) {
+            if (is_a($str, RawSql::class)) {
+                return $str->__toString();
+            }
+
             return "'" . $this->escapeString($str) . "'";
         }
 

system/Database/Postgre/Connection.php

@@ -13,6 +13,7 @@
 
 use CodeIgniter\Database\BaseConnection;
 use CodeIgniter\Database\Exceptions\DatabaseException;
+use CodeIgniter\Database\RawSql;
 use ErrorException;
 use stdClass;
 
@@ -181,6 +182,10 @@ public function escape($str)
         }
 
         if (is_string($str) || (is_object($str) && method_exists($str, '__toString'))) {
+            if (is_a($str, RawSql::class)) {
+                return $str->__toString();
+            }
+
             return pg_escape_literal($this->connID, $str);
         }
 

tests/system/Database/BaseConnectionTest.php

@@ -165,6 +165,20 @@ 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.

user_guide_src/source/database/call_function.rst

@@ -37,3 +37,18 @@ 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

@@ -0,0 +1,11 @@
+<?php
+
+    $stringArray = [' A simple string ', new RawSql('CURRENT_TIMESTAMP()'), false, null];
+
+    $escapedString = $db->escape($stringArray);
+
+    $this->assertSame("'A simple string'", $escapedString[0]); // adds quotes
+    $this->assertSame('CURRENT_TIMESTAMP()', $escapedString[1]); // does not add quotes
+    $this->assertSame(0, $escapedString[2]); // converts bool to 1 or 0
+    $this->assertSame('NULL', $escapedString[3]); // null returns NULL without quotes
+    $this->assertSame("'{braces}'", $escapedString[4]); // actual braces

user_guide_src/source/database/call_function/006.php

@@ -0,0 +1,15 @@
+<?php
+
+    $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 (id, title, name, date, last_update)
+        VALUES (DEFAULT, 'My title', 'My name', '2022-01-01', CURRENT_TIMESTAMP())
+    */