feat(database): support backed enum values

- Allow database escaping to use BackedEnum backing values
- Support BackedEnum values in query bindings and Query Builder binds
- Add focused tests and user guide examples

Signed-off-by: memleakd <121398829+memleakd@users.noreply.github.com>

Author: memleakd

system/Database/BaseConnection.php

@@ -13,6 +13,7 @@
 
 namespace CodeIgniter\Database;
 
+use BackedEnum;
 use Closure;
 use CodeIgniter\Database\Exceptions\DatabaseException;
 use CodeIgniter\Database\Exceptions\RetryableTransactionException;
@@ -1758,7 +1759,7 @@ abstract public function affectedRows(): int;
      * Escapes data based on type.
      * Sets boolean and null types
      *
-     * @param array|bool|float|int|object|string|null $str
+     * @param array|BackedEnum|bool|float|int|object|string|null $str
      *
      * @return ($str is array ? array : float|int|string)
      */
@@ -1768,6 +1769,10 @@ public function escape($str)
             return array_map($this->escape(...), $str);
         }
 
+        if ($str instanceof BackedEnum) {
+            $str = $str->value;
+        }
+
         if ($str instanceof Stringable) {
             if ($str instanceof RawSql) {
                 return $str->__toString();

system/Database/ConnectionInterface.php

@@ -13,6 +13,8 @@
 
 namespace CodeIgniter\Database;
 
+use BackedEnum;
+
 /**
  * @template TConnection
  * @template TResult
@@ -179,7 +181,7 @@ public function getLastQuery();
      * Escapes data based on type.
      * Sets boolean and null types.
      *
-     * @param array|bool|float|int|object|string|null $str
+     * @param array|BackedEnum|bool|float|int|object|string|null $str
      *
      * @return ($str is array ? array : float|int|string)
      */

system/Database/Postgre/Connection.php

@@ -13,6 +13,7 @@
 
 namespace CodeIgniter\Database\Postgre;
 
+use BackedEnum;
 use CodeIgniter\Database\BaseConnection;
 use CodeIgniter\Database\Exceptions\DatabaseException;
 use CodeIgniter\Database\RawSql;
@@ -354,7 +355,7 @@ public function affectedRows(): int
      *
      * Escapes data based on type
      *
-     * @param array|bool|float|int|object|string|null $str
+     * @param array|BackedEnum|bool|float|int|object|string|null $str
      *
      * @return ($str is array ? array : float|int|string)
      */
@@ -364,6 +365,10 @@ public function escape($str)
             $this->initialize();
         }
 
+        if ($str instanceof BackedEnum) {
+            $str = $str->value;
+        }
+
         if ($str instanceof Stringable) {
             if ($str instanceof RawSql) {
                 return $str->__toString();

tests/system/Database/BaseQueryTest.php

@@ -17,6 +17,8 @@
 use CodeIgniter\Test\Mock\MockConnection;
 use PHPUnit\Framework\Attributes\DataProvider;
 use PHPUnit\Framework\Attributes\Group;
+use Tests\Support\Enum\RoleEnum;
+use Tests\Support\Enum\StatusEnum;
 
 /**
  * @internal
@@ -242,6 +244,17 @@ public function testBindingAutoEscapesParameters(): void
         $this->assertSame($expected, $query->getQuery());
     }
 
+    public function testBindingBackedEnum(): void
+    {
+        $query = new Query($this->db);
+
+        $query->setQuery('SELECT * FROM users WHERE status = ? AND role = ?', [StatusEnum::ACTIVE, RoleEnum::ADMIN]);
+
+        $expected = "SELECT * FROM users WHERE status = 'active' AND role = 2";
+
+        $this->assertSame($expected, $query->getQuery());
+    }
+
     /**
      * @see https://github.com/codeigniter4/CodeIgniter4/issues/5114
      */

tests/system/Database/Builder/InsertTest.php

@@ -20,6 +20,7 @@
 use CodeIgniter\Test\CIUnitTestCase;
 use CodeIgniter\Test\Mock\MockConnection;
 use PHPUnit\Framework\Attributes\Group;
+use Tests\Support\Enum\StatusEnum;
 
 /**
  * @internal
@@ -65,6 +66,20 @@ public function testInsertArray(): void
         $this->assertSame($expectedBinds, $builder->getBinds());
     }
 
+    public function testInsertWithBackedEnum(): void
+    {
+        $builder = $this->db->table('jobs');
+
+        $builder->testMode()->insert([
+            'id'     => 1,
+            'status' => StatusEnum::ACTIVE,
+        ], true);
+
+        $expectedSQL = 'INSERT INTO "jobs" ("id", "status") VALUES (1, \'active\')';
+
+        $this->assertSame($expectedSQL, str_replace("\n", ' ', $builder->getCompiledInsert()));
+    }
+
     public function testInsertObject(): void
     {
         $builder = $this->db->table('jobs');

tests/system/Database/Builder/WhereTest.php

@@ -25,6 +25,8 @@
 use PHPUnit\Framework\Attributes\DataProvider;
 use PHPUnit\Framework\Attributes\Group;
 use stdClass;
+use Tests\Support\Enum\RoleEnum;
+use Tests\Support\Enum\StatusEnum;
 
 /**
  * @internal
@@ -400,6 +402,28 @@ public function testOrWhereSameColumn(): void
         $this->assertSame($expectedBinds, $builder->getBinds());
     }
 
+    public function testWhereWithBackedEnum(): void
+    {
+        $builder = $this->db->table('jobs');
+
+        $builder->where('status', StatusEnum::ACTIVE);
+
+        $expectedSQL = 'SELECT * FROM "jobs" WHERE "status" = \'active\'';
+
+        $this->assertSame($expectedSQL, str_replace("\n", ' ', $builder->getCompiledSelect()));
+    }
+
+    public function testWhereBetweenWithBackedEnums(): void
+    {
+        $builder = $this->db->table('jobs');
+
+        $builder->whereBetween('role', [RoleEnum::GUEST, RoleEnum::ADMIN]);
+
+        $expectedSQL = 'SELECT * FROM "jobs" WHERE "role" BETWEEN 0 AND 2';
+
+        $this->assertSame($expectedSQL, str_replace("\n", ' ', $builder->getCompiledSelect()));
+    }
+
     #[DataProvider('provideWhereColumnWithOperators')]
     public function testWhereColumnWithOperators(string $first, string $operator): void
     {
@@ -840,6 +864,17 @@ public function testWhereIn(): void
         $this->assertSame($expectedBinds, $builder->getBinds());
     }
 
+    public function testWhereInWithBackedEnums(): void
+    {
+        $builder = $this->db->table('jobs');
+
+        $builder->whereIn('status', [StatusEnum::ACTIVE, StatusEnum::INACTIVE]);
+
+        $expectedSQL = 'SELECT * FROM "jobs" WHERE "status" IN (\'active\',\'inactive\')';
+
+        $this->assertSame($expectedSQL, str_replace("\n", ' ', $builder->getCompiledSelect()));
+    }
+
     public function testWhereInSubQuery(): void
     {
         $expectedSQL = 'SELECT * FROM "jobs" WHERE "id" IN (SELECT "job_id" FROM "users_jobs" WHERE "user_id" = 3)';

tests/system/Database/Live/EscapeTest.php

@@ -18,6 +18,8 @@
 use CodeIgniter\Test\CIUnitTestCase;
 use CodeIgniter\Test\DatabaseTestTrait;
 use PHPUnit\Framework\Attributes\Group;
+use Tests\Support\Enum\RoleEnum;
+use Tests\Support\Enum\StatusEnum;
 
 /**
  * @internal
@@ -63,6 +65,16 @@ public function testEscapeStringable(): void
         $this->assertSame($expected, $sql);
     }
 
+    public function testEscapeStringBackedEnum(): void
+    {
+        $this->assertSame("'active'", $this->db->escape(StatusEnum::ACTIVE));
+    }
+
+    public function testEscapeIntBackedEnum(): void
+    {
+        $this->assertSame(2, $this->db->escape(RoleEnum::ADMIN));
+    }
+
     public function testEscapeString(): void
     {
         $expected = "SELECT * FROM brands WHERE name = 'O" . $this->char . "'Doules'";
@@ -111,7 +123,7 @@ public function testEscapeLikeStringDirect(): void
 
     public function testEscapeStringArray(): void
     {
-        $stringArray = [' A simple string ', new RawSql('CURRENT_TIMESTAMP()'), false, null];
+        $stringArray = [' A simple string ', new RawSql('CURRENT_TIMESTAMP()'), false, null, StatusEnum::ACTIVE, RoleEnum::ADMIN];
 
         $escapedString = $this->db->escape($stringArray);
 
@@ -125,5 +137,7 @@ public function testEscapeStringArray(): void
         }
 
         $this->assertSame('NULL', $escapedString[3]);
+        $this->assertSame("'active'", $escapedString[4]);
+        $this->assertSame(2, $escapedString[5]);
     }
 }

user_guide_src/source/changelogs/v4.8.0.rst

@@ -210,6 +210,7 @@ Database
 
 - Added ``afterCommit()`` and ``afterRollback()`` transaction callbacks to database connections. These callbacks run after the outermost transaction commits or rolls back. See :ref:`transactions-transaction-callbacks`.
 - Added ``inTransaction()`` to database connections to check whether the connection is inside an active CodeIgniter-managed transaction. See :ref:`transactions-checking-transaction-state`.
+- Added support for PHP ``BackedEnum`` values in database escaping, query bindings, and Query Builder bound values.
 - Prepared query execution failures now throw or store typed database exceptions such as ``UniqueConstraintViolationException`` and ``RetryableTransactionException`` when applicable, matching normal query failures.
 - Added ``RetryableTransactionException`` for driver-specific retryable transaction failures such as deadlocks and serialization failures. See :ref:`transactions-retryable-exceptions`.
 - Added the ``transaction()`` method to database connections to run a callback inside a transaction, with optional retry attempts for retryable transaction failures and scoped ``transException`` and ``resetTransStatus`` options. See :ref:`transactions-closure`.

user_guide_src/source/database/queries.rst

@@ -138,6 +138,10 @@ don't have to:
 
 .. literalinclude:: queries/009.php
 
+.. versionadded:: 4.8.0
+    ``$db->escape()`` accepts PHP ``BackedEnum`` values and escapes their backing
+    values.
+
 2. $db->escapeString()
 ======================
 
@@ -188,6 +192,13 @@ The secondary benefit of using binds is that the values are
 automatically escaped producing safer queries.
 You don't have to remember to manually escape data - the engine does it automatically for you.
 
+.. versionadded:: 4.8.0
+    Query bindings and Query Builder bound values accept PHP ``BackedEnum``
+    values. CodeIgniter uses the enum backing value when escaping the bound
+    value.
+
+.. literalinclude:: queries/032.php
+
 Named Bindings
 ==============
 

user_guide_src/source/database/queries/032.php

@@ -0,0 +1,8 @@
+<?php
+
+$db->table('users')->where('status', \UserStatus::Active)->get();
+
+$db->query(
+    'SELECT * FROM users WHERE status = ?',
+    [\UserStatus::Active],
+);