fix: reject null values in where() to prevent silent SQL logic errors

where('col', null) generated "column = NULL" which is always false in SQL.
Now throws QueryException pointing to whereNull()/whereNotNull().

Author: SoDaHo

src/Query/QueryBuilder.php

@@ -131,16 +131,46 @@ public function where(string|array $column, mixed $operatorOrValue = null, mixed
         // Array syntax: where(['active' => 1, 'role' => 'admin'])
         if (is_array($column)) {
             foreach ($column as $col => $val) {
+                if ($val === null) {
+                    throw new QueryException(
+                        message: 'Query failed',
+                        debugMessage: sprintf(
+                            'Cannot use null value for column "%s" in where(). Use whereNull(\'%s\') or whereNotNull(\'%s\') instead.',
+                            $col,
+                            $col,
+                            $col
+                        )
+                    );
+                }
                 $this->where($col, '=', $val);
             }
             return $this;
         }
 
         // Must have at least 2 arguments for string column
+        // Also catches where('col', null) — 2-argument form with null value
         if ($operatorOrValue === null) {
             throw new QueryException(
                 message: 'Query failed',
-                debugMessage: 'where() requires at least 2 arguments: where(column, value) or where(column, operator, value)'
+                debugMessage: sprintf(
+                    'Cannot use null value in where(). SQL "column = NULL" is always false. Use whereNull(\'%s\') or whereNotNull(\'%s\') instead.',
+                    $column,
+                    $column
+                )
+            );
+        }
+
+        // 3-argument form: where('col', '=', null) — reject null values
+        // Detect by checking if $operatorOrValue looks like an operator
+        if ($value === null && in_array(strtoupper(trim((string) $operatorOrValue)), self::ALLOWED_OPERATORS, true)) {
+            throw new QueryException(
+                message: 'Query failed',
+                debugMessage: sprintf(
+                    'Cannot use null value in where(). SQL "column %s NULL" is always false. Use whereNull(\'%s\') or whereNotNull(\'%s\') instead.',
+                    strtoupper(trim((string) $operatorOrValue)),
+                    $column,
+                    $column
+                )
             );
         }
 

tests/Unit/EdgeCaseTest.php

@@ -484,4 +484,103 @@ public function testDeleteWithoutLimitOrOrderByStillWorks(): void
 
         $this->assertSame(1, $affected);
     }
+
+    // =========================================================================
+    // WHERE NULL BUG FIX TEST
+    // Bug: where('column', null) generated "column = NULL" which is always false
+    // in SQL. Users must use whereNull()/whereNotNull() instead.
+    // =========================================================================
+
+    public function testWhereTwoArgNullThrowsException(): void
+    {
+        $db = Database::sqlite(':memory:');
+
+        $this->expectException(QueryException::class);
+
+        $db->table('users')->where('status', null);
+    }
+
+    public function testWhereThreeArgNullThrowsException(): void
+    {
+        $db = Database::sqlite(':memory:');
+
+        $this->expectException(QueryException::class);
+
+        $db->table('users')->where('status', '=', null);
+    }
+
+    public function testWhereArraySyntaxNullThrowsException(): void
+    {
+        $db = Database::sqlite(':memory:');
+
+        $this->expectException(QueryException::class);
+
+        $db->table('users')->where(['status' => null]);
+    }
+
+    public function testWhereNullExceptionSuggestsWhereNull(): void
+    {
+        $db = Database::sqlite(':memory:');
+
+        try {
+            $db->table('users')->where('status', null);
+            $this->fail('Expected QueryException was not thrown');
+        } catch (QueryException $e) {
+            $debug = $e->getDebugMessage() ?? '';
+            $this->assertStringContainsString('whereNull', $debug);
+            $this->assertStringContainsString('status', $debug);
+        }
+    }
+
+    public function testWhereThreeArgNullExceptionSuggestsWhereNull(): void
+    {
+        $db = Database::sqlite(':memory:');
+
+        try {
+            $db->table('users')->where('deleted_at', '=', null);
+            $this->fail('Expected QueryException was not thrown');
+        } catch (QueryException $e) {
+            $debug = $e->getDebugMessage() ?? '';
+            $this->assertStringContainsString('whereNull', $debug);
+            $this->assertStringContainsString('deleted_at', $debug);
+        }
+    }
+
+    public function testWhereIsNullThrowsExceptionSuggestsWhereNull(): void
+    {
+        $db = Database::sqlite(':memory:');
+
+        try {
+            $db->table('users')->where('deleted_at', 'IS', null);
+            $this->fail('Expected QueryException was not thrown');
+        } catch (QueryException $e) {
+            $debug = $e->getDebugMessage() ?? '';
+            $this->assertStringContainsString('whereNull', $debug);
+        }
+    }
+
+    public function testWhereIsNotNullThrowsExceptionSuggestsWhereNotNull(): void
+    {
+        $db = Database::sqlite(':memory:');
+
+        try {
+            $db->table('users')->where('deleted_at', 'IS NOT', null);
+            $this->fail('Expected QueryException was not thrown');
+        } catch (QueryException $e) {
+            $debug = $e->getDebugMessage() ?? '';
+            $this->assertStringContainsString('whereNotNull', $debug);
+        }
+    }
+
+    public function testWhereWithNonNullValuesStillWorks(): void
+    {
+        $db = Database::sqlite(':memory:');
+        $db->execute('CREATE TABLE users (id INTEGER PRIMARY KEY, status TEXT)');
+        $db->insert('users', ['status' => 'active']);
+
+        $result = $db->table('users')->where('status', 'active')->first();
+
+        $this->assertNotNull($result);
+        $this->assertSame('active', $result['status']);
+    }
 }