refactor and return false on failure

Author: michalsn

system/Model.php

@@ -724,7 +724,7 @@ protected function doProtectFieldsForInsert(array $row): array
      * @param array<string, mixed>|object $attributes
      * @param array<string, mixed>|object $values
      */
-    public function firstOrInsert(array|object $attributes, array|object $values = []): array|object|null
+    public function firstOrInsert(array|object $attributes, array|object $values = []): array|object|false
     {
         if (is_object($attributes)) {
             $attributes = $this->transformDataToArray($attributes, 'insert');
@@ -748,18 +748,18 @@ public function firstOrInsert(array|object $attributes, array|object $values = [
         try {
             $id = $this->insert($data);
         } catch (UniqueConstraintViolationException) {
-            return $this->where($attributes)->first();
+            return $this->where($attributes)->first() ?? false;
         }
 
         if ($id === false) {
             if ($this->db->getLastException() instanceof UniqueConstraintViolationException) {
-                return $this->where($attributes)->first();
+                return $this->where($attributes)->first() ?? false;
             }
 
-            return null;
+            return false;
         }
 
-        return $this->where($this->primaryKey, $id)->first();
+        return $this->where($this->primaryKey, $id)->first() ?? false;
     }
 
     public function update($id = null, $row = null): bool

tests/system/Models/FirstOrInsertModelTest.php

@@ -66,7 +66,7 @@ public function testValuesAreIgnoredWhenRecordExists(): void
             ['name' => 'Should Not Change', 'country' => 'XX'],
         );
 
-        $this->assertNotNull($row);
+        $this->assertNotFalse($row);
         $this->assertSame('Derek Jones', $row->name);
         $this->assertSame('US', $row->country);
     }
@@ -81,7 +81,7 @@ public function testInsertsNewRecordWhenNotFound(): void
             'country' => 'US',
         ]);
 
-        $this->assertNotNull($row);
+        $this->assertNotFalse($row);
         $this->assertSame('new@example.com', $row->email);
         $this->seeInDatabase('user', ['email' => 'new@example.com', 'deleted_at' => null]);
     }
@@ -95,7 +95,7 @@ public function testMergesValuesOnInsert(): void
             ['name' => 'New User', 'country' => 'CA'],
         );
 
-        $this->assertNotNull($row);
+        $this->assertNotFalse($row);
         $this->assertSame('New User', $row->name);
         $this->assertSame('CA', $row->country);
         $this->seeInDatabase('user', [
@@ -119,7 +119,7 @@ public function testAcceptsObjectForValues(): void
             $values,
         );
 
-        $this->assertNotNull($row);
+        $this->assertNotFalse($row);
         $this->assertSame('Object User', $row->name);
         $this->assertSame('DE', $row->country);
         $this->seeInDatabase('user', ['email' => 'object@example.com', 'deleted_at' => null]);
@@ -134,7 +134,7 @@ public function testAcceptsObjectForAttributes(): void
 
         $row = $this->model->firstOrInsert($attributes);
 
-        $this->assertNotNull($row);
+        $this->assertNotFalse($row);
         $this->assertSame('Derek Jones', $row->name);
         $this->seeNumRecords(4, 'user', ['deleted_at' => null]);
     }
@@ -183,7 +183,7 @@ protected function doInsert(array $row): bool
             ['name' => 'Race User', 'country' => 'US'],
         );
 
-        $this->assertNotNull($row);
+        $this->assertNotFalse($row);
         $this->assertSame('race@example.com', $row->email);
         // The "other process" inserted exactly one record.
         $this->seeNumRecords(1, 'user', ['email' => 'race@example.com', 'deleted_at' => null]);
@@ -218,12 +218,12 @@ protected function doInsert(array $row): bool
             ['name' => 'Race User', 'country' => 'US'],
         );
 
-        $this->assertNotNull($row);
+        $this->assertNotFalse($row);
         $this->assertSame('race@example.com', $row->email);
         $this->seeNumRecords(1, 'user', ['email' => 'race@example.com', 'deleted_at' => null]);
     }
 
-    public function testReturnsNullOnNonUniqueErrorWithDebugDisabled(): void
+    public function testReturnsFalseOnNonUniqueErrorWithDebugDisabled(): void
     {
         $this->disableDBDebug();
 
@@ -245,11 +245,11 @@ protected function doInsert(array $row): bool
             ['name' => 'Error User', 'country' => 'US'],
         );
 
-        $this->assertNull($result);
+        $this->assertFalse($result);
         $this->dontSeeInDatabase('user', ['email' => 'error@example.com']);
     }
 
-    public function testReturnsNullOnValidationFailure(): void
+    public function testReturnsFalseOnValidationFailure(): void
     {
         // Subclass with strict validation rules that the test data fails.
         $model = new class ($this->db) extends UserModel {
@@ -264,7 +264,7 @@ public function testReturnsNullOnValidationFailure(): void
             ['name' => 'Too Short'],
         );
 
-        $this->assertNull($result);
+        $this->assertFalse($result);
         $this->dontSeeInDatabase('user', ['email' => 'not-a-valid-email']);
         $this->assertNotEmpty($model->errors());
     }

user_guide_src/source/changelogs/v4.8.0.rst

@@ -168,10 +168,7 @@ Model
 =====
 
 - Added new ``chunkRows()`` method to ``CodeIgniter\Model`` for processing large datasets in smaller chunks.
-- Added new ``firstOrInsert()`` method to ``CodeIgniter\Model`` that finds the first row matching the given
-  attributes or inserts a new one. Uses an optimistic insert strategy to avoid race conditions, relying on
-  :php:class:`UniqueConstraintViolationException <CodeIgniter\\Database\\Exceptions\\UniqueConstraintViolationException>`
-  to detect concurrent inserts.
+- Added new ``firstOrInsert()`` method to ``CodeIgniter\Model`` that finds the first row matching the given attributes or inserts a new one. See :ref:`model-first-or-insert`.
 
 Libraries
 =========

user_guide_src/source/models/model.rst

@@ -656,7 +656,7 @@ ignored when a matching record already exists.
 .. literalinclude:: model/066.php
 
 The method returns the found or newly inserted row in the format defined by
-`$returnType`_, or ``null`` on failure (e.g., validation error or database
+`$returnType`_, or ``false`` on failure (e.g., validation error or database
 error when ``DBDebug`` is ``false``).
 
 .. note:: A database **unique constraint** on the lookup column(s) is required