where, whereNot, whereInList, contains: stricter matching for strings, null, and bools

Most calls behave the same: numbers still match numeric strings, so where('id', 5) matches '5' and where('price', 1) matches '1.00'. Three edge cases now match fewer rows:

- Two strings must match exactly: '01' no longer matches '1', and where('code', '0e123') no longer matches '0e999' (PHP's loose == read both as numbers - a wrong-row risk for hash lookups)
- null only matches null, like SQL IS NULL (it used to match '', 0, and false)
- true/false mean 1/0 (true used to match any truthy value, even 'abc')

All four methods share one helper (valueMatches). Checked the full matrix against MariaDB: same answers as a SQL WHERE except strings stay case-sensitive and 'abc' never equals 0. New tests pin each rule, and a partition test checks where() + whereNot() always split a set exactly in two. Docs, changelog, and UPGRADING updated.

Author: daveedis

CHANGELOG.md

@@ -98,6 +98,18 @@ the docs - IDEs show a strikethrough with the replacement.
 
 ### Behavior changes
 
+- `where()`, `whereNot()`, `whereInList()`, and `contains()` match values
+  more precisely. Most code sees no difference: numbers still match numeric
+  strings, so `where('id', 5)` matches `'5'` and `where('price', 1)` matches
+  `'1.00'`. Three edge cases changed:
+    - Two strings must match exactly: `'01'` no longer matches `'1'`, and
+      `where('code', '0e123')` no longer matches `'0e999'` (PHP's loose `==`
+      read both as numbers - a wrong-row risk for hash and token lookups)
+    - null only matches null, like SQL IS NULL (it used to match `''`, 0,
+      and false too)
+    - true/false mean 1/0 (true used to match any truthy value, even `'abc'`)
+
+  See [UPGRADING.md](UPGRADING.md).
 - A missing field stays a SmartNull through the whole chain instead of
   becoming an empty SmartString at the first method call. Same output as
   before (echoes `""`, `or()` still fires), but chains no longer dead-end:

UPGRADING.md

@@ -109,6 +109,30 @@ automatically unless your composer.json pins `itools/smartstring` lower.*
 >
 > Regex: `->\w+ \?\?` - also search `isset(` and `empty(` on row fields
 
+### Matching rules for `where()`, `whereNot()`, `whereInList()`, and `contains()`
+
+> Most calls behave the same: numbers still match numeric strings, so
+> `where('id', 5)` matches `'5'` and `where('price', 1)` matches `'1.00'`.
+> Three edge cases now match fewer rows:
+>
+> ```php
+> $rows->where('code', '0e123');  // before: also matched '0e999' (PHP read both strings as numbers)
+>                                 // after:  strings must match exactly ('01' vs '1' changed the same way)
+>
+> $rows->where('field', null);    // before: matched null, '', 0, and false
+>                                 // after:  matches only null, like SQL IS NULL
+>
+> $rows->where('active', true);   // before: matched anything truthy, even 'abc'
+>                                 // after:  true means 1, so it matches 1 and '1'
+> ```
+>
+> Fix:
+>
+> - For empty/non-empty checks, use `where($field)` / `whereNot($field)`
+> - When you mean a number, pass a number: `where('price', (float)$_GET['price'])`
+>
+> Regex: `->(where|whereNot|contains)\([^)]*(null|true|false)\s*\)`
+
 ### Silent changes
 
 > - `print_r()` and `var_dump()` show just the array data, like dumping a

docs/ai-reference.md

@@ -216,7 +216,7 @@ All three return `SmartNull` silently when there is no such element
 count(): int                  // also works via count($collection) (Countable)
 isEmpty(): bool               // no elements
 isNotEmpty(): bool            // any elements
-contains(mixed $value): bool  // any element == $value (loose; Smart args unwrap)
+contains(mixed $value): bool  // any element matches $value (where() rules; Smart args unwrap)
 ```
 
 Field-level checks (`isMissing()`, `isEmpty()`, `or()`, ...) are SmartString
@@ -242,8 +242,8 @@ All return a new collection; nested-only methods throw
 
 | Method                                                     | Behavior                                                                                                                                                                |
 |------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `where(string $field, mixed $value = null): static`        | Nested only. Keeps rows where `$field == $value` (loose; `'1'` matches 1; Smart args unwrap). Rows without the field are dropped. Chain calls for AND. Warns when `$field` is missing from the first row. Single-arg `where($field)` keeps rows where the field is non-empty (PHP `empty()` rule: NULL, false, 0, "0", "", missing are empty). NOTE: `where($f)` and `where($f, null)` differ - the latter is a loose == null match |
-| `whereNot(string $field, mixed $value = null): static`     | Nested only. Drops rows where `$field == $value`; rows WITHOUT the field are kept. Single-arg `whereNot($field)` keeps rows where the field is empty or missing (exact complement of `where($field)`)     |
+| `where(string $field, mixed $value = null): static`        | Nested only. Keeps rows where `$field` matches `$value`: strings match as exact text (`'0e12'` never matches `'0e99'`), numbers match numerically in either direction (`'1'` matches 1, 1 matches `'1.00'`), null matches only null (SQL IS NULL), bools compare as 1/0 on either side. Smart args unwrap. Rows without the field are dropped. Chain calls for AND. Warns when `$field` is missing from the first row. Single-arg `where($field)` keeps rows where the field is non-empty (PHP `empty()` rule: NULL, false, 0, "0", "", missing are empty). NOTE: `where($f)` and `where($f, null)` differ - the latter matches only stored NULLs |
+| `whereNot(string $field, mixed $value = null): static`     | Nested only. Drops rows where `$field` matches `$value` (same matching rules as `where()`); rows WITHOUT the field are kept. Single-arg `whereNot($field)` keeps rows where the field is empty or missing (exact complement of `where($field)`)     |
 | `whereInList(string $field, mixed $value): static`         | Nested only. Keeps rows where tab-separated `$field` contains `$value` as a whole value (`"\tmenu\tfooter\t"` format, CMS Builder checkbox/multi-select fields) or equals it as a plain single value. Never substring matching |
 | `filter(?callable $callback = null): static`               | Both shapes. Callback receives raw `($value, $key)`, keeps on true. No callback: removes falsy (`""`, 0, null, false). Keys preserved like `array_filter()` - chain `values()` for a clean JSON array |
 | `sort(int $flags = SORT_REGULAR): static`                  | Flat only. Sorts ascending by value, renumbers keys. `$flags` choose comparison only; `SORT_ASC`/`SORT_DESC` throw `InvalidArgumentException` (sort descending in SQL)  |

docs/filtering-and-sorting.md

@@ -26,9 +26,12 @@ $active = $users->where('status', 'Active');                        // Jean and
 $admins = $users->where('status', 'Active')->where('role', 'admin');  // just Jean
 ```
 
-Databases and forms often hand numbers back as strings, so `where()`
-compares loosely: `'1'` matches `1`. When you need a strict match,
-`filter()` (below) takes a callback where you can compare with `===`.
+Databases and forms often hand numbers back as strings, so numbers and
+numeric strings match: `'1'` matches `1`, and `where('price', 1)` matches a
+DECIMAL column's `'1.00'`. Everything else is what you'd expect: two strings
+must match exactly (case-sensitive), null only matches null, and true/false
+mean 1/0. When you need full type-sensitive matching, `filter()` (below)
+takes a callback where you can compare with `===`.
 
 With just a field name, `where()` keeps the rows where that field has a
 truthy value, following PHP's `empty()` rules (NULL, false, 0, `"0"`, and
@@ -127,7 +130,8 @@ echo $tags->sort()->implode(', ');  // Apache, MySQL, PHP
 
 Use `unique()` to drop repeated values from a flat list, keeping the first
 of each, and `contains()` to ask whether a value is in the list at all.
-Both compare loosely, so `1` and `'1'` count as the same value:
+Both treat `1` and `'1'` as the same value (`contains()` follows the same
+matching rules as `where()`):
 
 ```php
 $tags = SmartArrayHtml::new(['PHP', 'MySQL', 'PHP', 'Apache']);

docs/method-reference.md

@@ -54,12 +54,12 @@ and objects are always truthy in PHP, so test for missing values with
 
 *These return plain values, typically used in if statements.*
 
-| Method               | Description                                                                    |
-|----------------------|--------------------------------------------------------------------------------|
-| `->count()`          | Returns the number of elements                                                 |
-| `->isEmpty()`        | Returns true when there are no elements                                        |
-| `->isNotEmpty()`     | Returns true when there are any elements                                       |
-| `->contains($value)` | Returns true when any element loosely equals `$value` (==, so `"5"` matches 5) |
+| Method               | Description                                                                                  |
+|----------------------|----------------------------------------------------------------------------------------------|
+| `->count()`          | Returns the number of elements                                                               |
+| `->isEmpty()`        | Returns true when there are no elements                                                      |
+| `->isNotEmpty()`     | Returns true when there are any elements                                                     |
+| `->contains($value)` | Returns true when any element matches `$value` (same rules as `where()`, so `"5"` matches 5) |
 
 ### [Row Position](outputting-html.md#loop-layout-isfirst-islast-position)
 
@@ -76,15 +76,15 @@ wrappers, and loop layout.*
 
 *These return a new collection and leave the original unchanged.*
 
-| Method                          | Description                                                                                                                                                                                                |
-|---------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `->where($field, $value)`       | Keeps rows where `$field` loosely equals `$value` (==, so `'1'` matches 1); chain calls to match several fields. With `$field` alone, keeps rows where it's non-empty (PHP `empty()` rule)                 |
-| `->whereNot($field, $value)`    | Drops rows where `$field` loosely equals `$value`; rows without the field are kept. With `$field` alone, keeps rows where it's empty or missing                                                            |
-| `->whereInList($field, $value)` | Keeps rows whose tab-separated `$field` contains `$value` (CMS Builder checkbox and multi-select format); matches whole values, never substrings                                                           |
-| `->filter($callback)`           | Keeps elements where `$callback` returns true (closures receive plain PHP values as `($value, $key)`); with no callback, removes falsy values (PHP falsy rule: `""`, `"0"`, 0, NULL, false); keys are kept |
-| `->sort($flags)`                | Sorts a flat list ascending by value, renumbering keys; `$flags` choose how values compare (default `SORT_REGULAR`); `SORT_ASC`/`SORT_DESC` throw, sort descending in SQL                                  |
-| `->sortBy($field, $flags)`      | Sorts rows ascending by `$field`; pass `SORT_NATURAL` to sort numbers the way people read them                                                                                                             |
-| `->unique()`                    | Removes duplicate values from a flat list, keeping the first of each and preserving keys (compares as text, so 1 and `'1'` match); chain `->values()` to renumber                                          |
+| Method                          | Description                                                                                                                                                                                                                                  |
+|---------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `->where($field, $value)`       | Keeps rows where `$field` matches `$value` (`'1'` matches 1, but two strings must match exactly, and null only matches null); chain calls to match several fields. With `$field` alone, keeps rows where it's non-empty (PHP `empty()` rule) |
+| `->whereNot($field, $value)`    | Drops rows where `$field` matches `$value` (same rules as `where()`); rows without the field are kept. With `$field` alone, keeps rows where it's empty or missing                                                                           |
+| `->whereInList($field, $value)` | Keeps rows whose tab-separated `$field` contains `$value` (CMS Builder checkbox and multi-select format); matches whole values, never substrings                                                                                             |
+| `->filter($callback)`           | Keeps elements where `$callback` returns true (closures receive plain PHP values as `($value, $key)`); with no callback, removes falsy values (PHP falsy rule: `""`, `"0"`, 0, NULL, false); keys are kept                                   |
+| `->sort($flags)`                | Sorts a flat list ascending by value, renumbering keys; `$flags` choose how values compare (default `SORT_REGULAR`); `SORT_ASC`/`SORT_DESC` throw, sort descending in SQL                                                                    |
+| `->sortBy($field, $flags)`      | Sorts rows ascending by `$field`; pass `SORT_NATURAL` to sort numbers the way people read them                                                                                                                                               |
+| `->unique()`                    | Removes duplicate values from a flat list, keeping the first of each and preserving keys (compares as text, so 1 and `'1'` match); chain `->values()` to renumber                                                                            |
 
 ### [Transforming and Grouping](transforming-and-grouping.md)
 

src/SmartArrayBase.php

@@ -498,6 +498,23 @@ public static function getRawValue(mixed $value): mixed
         };
     }
 
+    /**
+     * How where(), whereNot(), and contains() decide two values match:
+     * numbers match numeric strings (5 matches '5'), two strings must match
+     * exactly, null only matches null, and true/false mean 1/0.
+     * Callers unwrap Smart values with getRawValue() first.
+     */
+    private static function valueMatches(mixed $rowValue, mixed $value): bool
+    {
+        $value    = is_bool($value)    ? (int)$value    : $value;
+        $rowValue = is_bool($rowValue) ? (int)$rowValue : $rowValue;
+        return match (true) {
+            $value === null || $rowValue === null     => $value === $rowValue,
+            is_string($value) && is_string($rowValue) => $value === $rowValue,
+            default                                   => $value == $rowValue, // PHP 8 numeric comparison, e.g. 1 == '1.00'
+        };
+    }
+
     //endregion
     //region Array Information
 
@@ -526,15 +543,22 @@ public function isNotEmpty(): bool
     }
 
     /**
-     * Check if array contains a specific value (loose == comparison).
+     * Check if array contains a specific value.
      *
-     * Loose comparison means types don't need to match: contains('1') matches
-     * 1 and true, and contains(null) matches '' and false. For strict matching
-     * use in_array($value, $arr->toArray(), true).
+     * Values match the same way where() does: contains(5) matches '5', but two
+     * strings must match exactly. For strict type checks use
+     * in_array($value, $arr->toArray(), true).
      */
     public function contains(mixed $value): bool
     {
-        return in_array(self::getRawValue($value), $this->toArray());
+        $value = self::getRawValue($value);
+        foreach ($this->toArray() as $element) {
+            if (self::valueMatches($element, $value)) {
+                return true;
+            }
+        }
+
+        return false;
     }
 
     //endregion
@@ -643,7 +667,12 @@ public function filter(?callable $callback = null): static
      * Returns a new SmartArray containing only elements where a field matches a value.
      * Only works on nested arrays (throws on flat).
      *
-     * Uses loose comparison (==) to allow matching between different types (e.g., '1' == 1).
+     * How values match:
+     * - Numbers match numeric strings: where('id', 5) matches '5', where('price', 1) matches '1.00'
+     * - Two strings must match exactly: where('zip', '01000') won't match '1000'
+     * - null only matches null, like SQL IS NULL (use where('field') for non-empty checks)
+     * - true/false mean 1/0, like MySQL checkbox columns
+     *
      * Chain multiple where() calls to filter by multiple fields.
      *
      * With just a field name, keeps rows where that field is non-empty
@@ -684,7 +713,7 @@ public function where(array|string $field, mixed $value = null): static
             // repeated 4x, see the first where() loop for why
             $matches = [];
             foreach ($this->toArray() as $key => $row) {
-                if (is_array($row) && array_key_exists($field, $row) && $row[$field] == $value) {  // intentional loose comparison
+                if (is_array($row) && array_key_exists($field, $row) && self::valueMatches($row[$field], $value)) {
                     $matches[$key] = $row;
                 }
             }
@@ -715,7 +744,7 @@ public function where(array|string $field, mixed $value = null): static
      * Returns a new SmartArray excluding elements where a field matches a value.
      * The inverse of where(). Only works on nested arrays (throws on flat).
      *
-     * Uses loose comparison (==) to match where() behavior.
+     * Matches values the same way where() does.
      *
      * With just a field name, keeps rows where that field is empty
      * (PHP empty() rule: NULL, false, 0, "0", "", and missing fields are empty).
@@ -750,7 +779,7 @@ public function whereNot(string $field, mixed $value = null): static
         // repeated 4x, see the first where() loop for why
         $matches = [];
         foreach ($this->toArray() as $key => $row) {
-            if (is_array($row) && (!array_key_exists($field, $row) || $row[$field] != $value)) {  // intentional loose comparison
+            if (is_array($row) && (!array_key_exists($field, $row) || !self::valueMatches($row[$field], $value))) {
                 $matches[$key] = $row;
             }
         }
@@ -764,6 +793,7 @@ public function whereNot(string $field, mixed $value = null): static
      * multi-select fields). Does not perform substring matching.
      *
      * Handles both delimited format ("\tmenu\tfooter\t") and plain single values ("menu").
+     * Plain single values match the same way where() does.
      *
      *     $menuPages   = $pages->whereInList('show_on', 'menu');
      *     $footerPages = $pages->whereInList('show_on', 'footer');
@@ -788,7 +818,11 @@ public function whereInList(string $field, mixed $value): static
             if (!isset($row[$field])) {
                 continue;
             }
-            if ($row[$field] == $value || (is_string($row[$field]) && str_contains($row[$field], "\t$value\t"))) {  // intentional loose comparison
+            $fieldValue = $row[$field];
+            $isMatch    = is_string($fieldValue)
+                ? $fieldValue === $value || str_contains($fieldValue, "\t$value\t") // exact text, like where()
+                : $fieldValue == $value;                                            // non-string fields match numerically, e.g. int 2 matches '2'
+            if ($isMatch) {
                 $matches[$key] = $row;
             }
         }