docs: add about RawSql

Author: kenjis

user_guide_src/source/changelogs/v4.2.0.rst

@@ -64,7 +64,9 @@ Others
 - Added 4th parameter ``$includeDir`` to ``get_filenames()``. See :php:func:`get_filenames`.
 - HTML helper ``script_tag()`` now uses ``null`` values to write boolean attributes in minimized form: ``<script src="..." defer />``. See the sample code for :php:func:`script_tag`.
 - RouteCollection::addRedirect() can now use placeholders.
-
+- QueryBuilder raw SQL string support
+    - Added the class ``CodeIgniter\Database\RawSql`` which expresses raw SQL strings.
+    - :ref:`select() <query-builder-select-rawsql>`, :ref:`where() <query-builder-where-rawsql>`, :ref:`like() <query-builder-like-rawsql>` accept the ``CodeIgniter\Database\RawSql`` instance.
 
 Changes
 *******

user_guide_src/source/database/query_builder.rst

@@ -117,6 +117,17 @@ escaping of fields may break them.
 
 .. literalinclude:: query_builder/009.php
 
+.. _query-builder-select-rawsql:
+
+RawSql
+^^^^^^
+
+Since v4.2.0, ``$builder->select()`` accepts a ``CodeIgniter\Database\RawSql`` instance, which expresses raw SQL strings.
+
+.. literalinclude:: query_builder/099.php
+
+.. warning:: When you use ``RawSql``, you MUST escape the data manually. Failure to do so could result in SQL injections.
+
 $builder->selectMax()
 ---------------------
 
@@ -283,9 +294,20 @@ methods:
 
         .. literalinclude:: query_builder/027.php
 
+.. _query-builder-where-rawsql:
+
+5. RawSql
+^^^^^^^^^
+
+    Since v4.2.0, ``$builder->where()`` accepts a ``CodeIgniter\Database\RawSql`` instance, which expresses raw SQL strings.
+
+    .. literalinclude:: query_builder/100.php
+
+    .. warning:: When you use ``RawSql``, you MUST escape the data manually. Failure to do so could result in SQL injections.
+
 .. _query-builder-where-subquery:
 
-5. Subqueries
+6. Subqueries
 ^^^^^^^^^^^^^
 
     .. literalinclude:: query_builder/028.php
@@ -387,6 +409,17 @@ searches.
 
        .. literalinclude:: query_builder/041.php
 
+.. _query-builder-like-rawsql:
+
+3. RawSql
+^^^^^^^^^
+
+    Since v4.2.0, ``$builder->like()`` accepts a ``CodeIgniter\Database\RawSql`` instance, which expresses raw SQL strings.
+
+    .. literalinclude:: query_builder/101.php
+
+    .. warning:: When you use ``RawSql``, you MUST escape the data manually. Failure to do so could result in SQL injections.
+
 $builder->orLike()
 ------------------
 

user_guide_src/source/database/query_builder/099.php

@@ -0,0 +1,7 @@
+<?php
+
+use CodeIgniter\Database\RawSql;
+
+$sql = 'REGEXP_SUBSTR(ral_anno,"[0-9]{1,2}([,.][0-9]{1,3})([,.][0-9]{1,3})") AS ral';
+$builder->select(new RawSql($sql));
+$query = $builder->get();

user_guide_src/source/database/query_builder/100.php

@@ -0,0 +1,6 @@
+<?php
+
+use CodeIgniter\Database\RawSql;
+
+$sql = "id > 2 AND name != 'Accountant'";
+$builder->where(new RawSql($sql));

user_guide_src/source/database/query_builder/101.php

@@ -0,0 +1,7 @@
+<?php
+
+use CodeIgniter\Database\RawSql;
+
+$sql    = "CONCAT(users.name, ' ', IF(users.surname IS NULL OR users.surname = '', '', users.surname))";
+$rawSql = new RawSql($sql);
+$builder->like($rawSql, 'value', 'both');