docs: add about RawSql

codeigniter4 · Apr 13, 2022 · c8adf05 · c8adf05
1 parent ea381a1
commit c8adf05
Show file tree

Hide file tree

Showing 5 changed files with 57 additions and 1 deletion.
diff --git a/user_guide_src/source/changelogs/v4.2.0.rst b/user_guide_src/source/changelogs/v4.2.0.rst
@@ -38,6 +38,9 @@ Enhancements
  - The log format has also changed. If users are depending on the log format in their apps, the new log format is "<1-based count> <cleaned filepath>(<line>): <class><function><args>"
 - Added support for webp files to **app/Config/Mimes.php**.
 - Added 4th parameter ``$includeDir`` to ``get_filenames()``. See :php:func:`get_filenames`.
+- 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
 *******

diff --git a/user_guide_src/source/database/query_builder.rst b/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()
 ------------------
 

diff --git a/user_guide_src/source/database/query_builder/099.php b/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();
diff --git a/user_guide_src/source/database/query_builder/100.php b/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));
diff --git a/user_guide_src/source/database/query_builder/101.php b/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');