refactor: complete backed enum bind support

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

Author: memleakd

system/Database/BaseBuilder.php

@@ -13,6 +13,7 @@
 
 namespace CodeIgniter\Database;
 
+use BackedEnum;
 use Closure;
 use CodeIgniter\Database\Exceptions\DatabaseException;
 use CodeIgniter\Database\Exceptions\DataException;
@@ -3939,7 +3940,7 @@ protected function objectToArray($object)
         $array = [];
 
         foreach (get_object_vars($object) as $key => $val) {
-            if ((! is_object($val) || $val instanceof RawSql) && ! is_array($val)) {
+            if (($val instanceof BackedEnum || ! is_object($val) || $val instanceof RawSql) && ! is_array($val)) {
                 $array[$key] = $val;
             }
         }

system/Database/BasePreparedQuery.php

@@ -14,6 +14,7 @@
 namespace CodeIgniter\Database;
 
 use ArgumentCountError;
+use BackedEnum;
 use CodeIgniter\Database\Exceptions\DatabaseException;
 use CodeIgniter\Events\Events;
 use CodeIgniter\Exceptions\BadMethodCallException;
@@ -122,6 +123,12 @@ abstract public function _prepare(string $sql, array $options = []);
      */
     public function execute(...$data)
     {
+        foreach ($data as $key => $value) {
+            if ($value instanceof BackedEnum) {
+                $data[$key] = $value->value;
+            }
+        }
+
         // Execute the Query.
         $startTime = microtime(true);
 

tests/system/Database/Builder/InsertTest.php

@@ -80,6 +80,20 @@ public function testInsertWithBackedEnum(): void
         $this->assertSame($expectedSQL, str_replace("\n", ' ', $builder->getCompiledInsert()));
     }
 
+    public function testInsertObjectWithBackedEnum(): void
+    {
+        $builder = $this->db->table('jobs');
+
+        $builder->testMode()->insert((object) [
+            '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/Live/PreparedQueryTest.php

@@ -23,6 +23,7 @@
 use CodeIgniter\Test\DatabaseTestTrait;
 use PHPUnit\Framework\Attributes\Group;
 use Tests\Support\Database\Seeds\CITestSeeder;
+use Tests\Support\Enum\StatusEnum;
 
 /**
  * @internal
@@ -286,6 +287,19 @@ public function testExecuteSelectQueryAndCheckTypeAndResult(): void
         $this->assertSame($expectedRow, $result->getRowArray());
     }
 
+    public function testExecuteWithBackedEnum(): void
+    {
+        $this->query = $this->db->prepare(static fn ($db) => $db->table('team_members')
+            ->select('person_id')
+            ->where('status', StatusEnum::PENDING)
+            ->get());
+
+        $result = $this->query->execute(StatusEnum::ACTIVE);
+
+        $this->assertInstanceOf(ResultInterface::class, $result);
+        $this->assertCount(2, $result->getResultArray());
+    }
+
     public function testExecuteSelectQueryManualAndCheckTypeAndResult(): void
     {
         $this->query = $this->db->prepare(static function ($db): Query {

user_guide_src/source/database/queries.rst

@@ -193,9 +193,9 @@ 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.
+    Query bindings, prepared query values, and Query Builder bound values accept
+    PHP ``BackedEnum`` values. CodeIgniter uses the enum backing value before
+    escaping or passing the value to the database driver.
 
 .. literalinclude:: queries/032.php
 
@@ -319,6 +319,10 @@ query:
 
 .. literalinclude:: queries/019.php
 
+.. versionadded:: 4.8.0
+    Prepared query values accept PHP ``BackedEnum`` values and pass their
+    backing values to the database driver.
+
 For queries of type "write" it returns true or false, indicating the success or failure of the query.
 For queries of type "read" it returns a standard :doc:`result set </database/results>`.