When/WhenNot methods for db in a trait

system/Database/BaseBuilder.php

@@ -14,6 +14,7 @@
 use Closure;
 use CodeIgniter\Database\Exceptions\DatabaseException;
 use CodeIgniter\Database\Exceptions\DataException;
+use CodeIgniter\Traits\ConditionalTrait;
 use InvalidArgumentException;
 
 /**
@@ -25,6 +26,8 @@
  */
 class BaseBuilder
 {
+    use ConditionalTrait;
+
     /**
      * Reset DELETE data flag
      *

system/Traits/ConditionalTrait.php

@@ -0,0 +1,61 @@
+<?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.
+ */
+
+namespace CodeIgniter\Traits;
+
+trait ConditionalTrait
+{
+    /**
+     * Only runs the query when $condition evaluates to true
+     *
+     * @template TWhen of mixed
+     *
+     * @phpstan-param TWhen                         $condition
+     * @phpstan-param callable(self, TWhen): mixed  $callback
+     * @phpstan-param (callable(self): mixed)|null  $defaultCallback
+     * @param array|bool|float|int|object|resource|string|null $condition
+     *
+     * @return $this
+     */
+    public function when($condition, callable $callback, ?callable $defaultCallback = null): self
+    {
+        if ($condition) {
+            $callback($this, $condition);
+        } elseif ($defaultCallback) {
+            $defaultCallback($this);
+        }
+
+        return $this;
+    }
+
+    /**
+     * Only runs the query when $condition evaluates to false
+     *
+     * @template TWhenNot of mixed
+     *
+     * @phpstan-param TWhenNot                        $condition
+     * @phpstan-param callable(self, TWhenNot): mixed $callback
+     * @phpstan-param (callable(self): mixed)|null    $defaultCallback
+     * @param array|bool|float|int|object|resource|string|null $condition
+     *
+     * @return $this
+     */
+    public function whenNot($condition, callable $callback, ?callable $defaultCallback = null): self
+    {
+        if (! $condition) {
+            $callback($this, $condition);
+        } elseif ($defaultCallback) {
+            $defaultCallback($this);
+        }
+
+        return $this;
+    }
+}

tests/system/Database/Builder/WhenTest.php

@@ -0,0 +1,165 @@
+<?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.
+ */
+
+namespace CodeIgniter\Database\Builder;
+
+use CodeIgniter\Test\CIUnitTestCase;
+use CodeIgniter\Test\Mock\MockConnection;
+
+/**
+ * @internal
+ */
+final class WhenTest extends CIUnitTestCase
+{
+    /**
+     * @var MockConnection
+     */
+    protected $db;
+
+    protected function setUp(): void
+    {
+        parent::setUp();
+
+        $this->db = new MockConnection([]);
+    }
+
+    public function testWhenTrue()
+    {
+        $builder = $this->db->table('jobs');
+
+        $expectedSQL = 'SELECT * FROM "jobs"';
+        $this->assertSame($expectedSQL, str_replace("\n", ' ', $builder->getCompiledSelect()));
+
+        $builder = $builder->when(true, static function ($query) {
+            $query->select('id');
+        });
+
+        $expectedSQL = 'SELECT "id" FROM "jobs"';
+        $this->assertSame($expectedSQL, str_replace("\n", ' ', $builder->getCompiledSelect()));
+    }
+
+    public function testWhenTruthy()
+    {
+        $builder = $this->db->table('jobs');
+
+        $builder = $builder->when('abc', static function ($query) {
+            $query->select('id');
+        });
+
+        $expectedSQL = 'SELECT "id" FROM "jobs"';
+        $this->assertSame($expectedSQL, str_replace("\n", ' ', $builder->getCompiledSelect()));
+    }
+
+    public function testWhenRunsDefaultWhenFalse()
+    {
+        $builder = $this->db->table('jobs');
+
+        $builder = $builder->when(false, static function ($query) {
+            $query->select('id');
+        }, static function ($query) {
+            $query->select('name');
+        });
+
+        $expectedSQL = 'SELECT "name" FROM "jobs"';
+        $this->assertSame($expectedSQL, str_replace("\n", ' ', $builder->getCompiledSelect()));
+    }
+
+    public function testWhenDoesntModifyWhenFalse()
+    {
+        $builder = $this->db->table('jobs');
+
+        $builder = $builder->when(false, static function ($query) {
+            $query->select('id');
+        });
+
+        $expectedSQL = 'SELECT * FROM "jobs"';
+        $this->assertSame($expectedSQL, str_replace("\n", ' ', $builder->getCompiledSelect()));
+    }
+
+    public function testWhenPassesParemeters()
+    {
+        $builder = $this->db->table('jobs');
+        $name    = 'developer';
+
+        $builder = $builder->when($name, static function ($query, $name) {
+            $query->where('name', $name);
+        });
+
+        $expectedSQL = 'SELECT * FROM "jobs" WHERE "name" = \'developer\'';
+        $this->assertSame($expectedSQL, str_replace("\n", ' ', $builder->getCompiledSelect()));
+    }
+
+    public function testWhenNotFalse()
+    {
+        $builder = $this->db->table('jobs');
+
+        $expectedSQL = 'SELECT * FROM "jobs"';
+        $this->assertSame($expectedSQL, str_replace("\n", ' ', $builder->getCompiledSelect()));
+
+        $builder = $builder->whenNot(false, static function ($query) {
+            $query->select('id');
+        });
+
+        $expectedSQL = 'SELECT "id" FROM "jobs"';
+        $this->assertSame($expectedSQL, str_replace("\n", ' ', $builder->getCompiledSelect()));
+    }
+
+    public function testWhenNotFalsey()
+    {
+        $builder = $this->db->table('jobs');
+
+        $builder = $builder->whenNot('0', static function ($query) {
+            $query->select('id');
+        });
+
+        $expectedSQL = 'SELECT "id" FROM "jobs"';
+        $this->assertSame($expectedSQL, str_replace("\n", ' ', $builder->getCompiledSelect()));
+    }
+
+    public function testWhenNotRunsDefaultWhenTrue()
+    {
+        $builder = $this->db->table('jobs');
+
+        $builder = $builder->whenNot(true, static function ($query) {
+            $query->select('id');
+        }, static function ($query) {
+            $query->select('name');
+        });
+
+        $expectedSQL = 'SELECT "name" FROM "jobs"';
+        $this->assertSame($expectedSQL, str_replace("\n", ' ', $builder->getCompiledSelect()));
+    }
+
+    public function testWhenNotDoesntModifyWhenFalse()
+    {
+        $builder = $this->db->table('jobs');
+
+        $builder = $builder->whenNot(true, static function ($query) {
+            $query->select('id');
+        });
+
+        $expectedSQL = 'SELECT * FROM "jobs"';
+        $this->assertSame($expectedSQL, str_replace("\n", ' ', $builder->getCompiledSelect()));
+    }
+
+    public function testWhenNotPassesParemeters()
+    {
+        $builder = $this->db->table('jobs');
+        $name    = '0';
+
+        $builder = $builder->whenNot($name, static function ($query, $name) {
+            $query->where('name', $name);
+        });
+
+        $expectedSQL = 'SELECT * FROM "jobs" WHERE "name" = \'0\'';
+        $this->assertSame($expectedSQL, str_replace("\n", ' ', $builder->getCompiledSelect()));
+    }
+}

user_guide_src/source/changelogs/v4.3.0.rst

@@ -126,6 +126,7 @@ Database
 - Improved the SQL structure for ``Builder::updateBatch()``. See :ref:`update-batch` for the details.
 - Improved data returned by ``BaseConnection::getForeignKeyData()``. All DBMS returns the same structure.
 - ``Forge::addForeignKey()`` now includes a name parameter to manual set foreign key names. Not supported in SQLite3.
+- Added ``when()`` and ``whenNot()`` methods to conditionally add clauses to the query. See :ref:`BaseBuilder::when() <db-builder-when>` for details.
 
 Model
 =====

user_guide_src/source/database/query_builder.rst

@@ -1022,6 +1022,48 @@ that it produces a **DELETE** SQL string instead of an **INSERT** SQL string.
 
 For more information view documentation for ``$builder->getCompiledInsert()``.
 
+**********************
+Conditional Statements
+**********************
+
+.. _db-builder-when:
+
+When
+====
+
+$builder->when()
+----------------
+
+This allows modifying the query based on a condition without breaking out of the
+query builder chain. The first parameter is the condition, and it should evaluate
+to a boolean. The second parameter is a callable that will be ran
+when the condition is true.
+
+For example, you might only want to apply a given WHERE statement based on the
+value sent within an HTTP request:
+
+.. literalinclude:: query_builder/105.php
+
+Since the condition is evaluated as ``true``, the callable will be called. The value
+set in the condition will be passed as the second parameter to the callable so it
+can be used in the query.
+
+Sometimes you might want to apply a different statement if the condition evaluates to false.
+This can be accomplished by providing a second closure:
+
+.. literalinclude:: query_builder/106.php
+
+WhenNot
+=======
+
+$builder->whenNot()
+-------------------
+
+This works exactly the same way as ``$builder->when()`` except that it will
+only run the callable when the condition evaluates to ``false``, instead of ``true`` like ``when()``.
+
+.. literalinclude:: query_builder/107.php
+
 ***************
 Method Chaining
 ***************

user_guide_src/source/database/query_builder/105.php

@@ -0,0 +1,9 @@
+<?php
+
+$status = service('request')->getPost('status');
+
+$users = $this->db->table('users')
+    ->when($status, static function ($query, $status) {
+        $query->where('status', $status);
+    })
+    ->get();

user_guide_src/source/database/query_builder/106.php

@@ -0,0 +1,11 @@
+<?php
+
+$onlyInactive = service('request')->getPost('return_inactive');
+
+$users = $this->db->table('users')
+    ->when($onlyInactive, static function ($query, $onlyInactive) {
+        $query->where('status', 'inactive');
+    }, static function ($query) {
+        $query->where('status', 'active');
+    })
+    ->get();

user_guide_src/source/database/query_builder/107.php

@@ -0,0 +1,9 @@
+<?php
+
+$status = service('request')->getPost('status');
+
+$users = $this->db->table('users')
+    ->whenNot($status, static function ($query, $status) {
+        $query->where('active', 0);
+    })
+    ->get();