where, sortBy, indexBy and friends: throw on mixed arrays instead of silently skipping scalars

- row-only methods each did something different when a scalar sat next to rows:
  most skipped it, sortBy kept it, where/whereNot dropped it from both sides
  (so where + whereNot didn't add up to the whole collection)
- a scalar next to rows means the array was built wrong (wrapped an API response
  one level too high, or assigned a value onto a result set), so now
  assertNestedArray() requires every element to be a row and throws naming the
  bad element: "where(): Expected a nested array of rows, but element 'count'
  is not a row (int)"
- fast: the existing rowsOnly flag makes the check O(1) for result sets; only a
  stale flag triggers a rescan, which repairs the flag on the way through
- empty arrays still pass, DB results can never hit this
- removed the per-loop is_array() guards the assert makes dead, updated
  CHANGELOG/UPGRADING/ai-reference, converted the old skip-behavior tests to
  expect the throw

Author: daveedis

CHANGELOG.md

@@ -110,6 +110,15 @@ the docs - IDEs show a strikethrough with the replacement.
     - true/false mean 1/0 (true used to match any truthy value, even `'abc'`)
 
   See [UPGRADING.md](UPGRADING.md).
+- Row-only methods (`where()`, `whereNot()`, `whereInList()`, `sortBy()`,
+  `indexBy()`, `groupBy()`, `column()`, `columnAt()`) throw
+  `InvalidArgumentException` naming the offending element when the array
+  mixes rows and scalar values, instead of silently skipping the scalars
+  (`sortBy()` kept them). A scalar next to rows means the array was built
+  wrong - usually a wrapped API response (`['count' => 5, 'items' => [...]]`)
+  or a value assigned onto a result set - and skipping it hid the mistake.
+  Database results and empty arrays are unaffected. 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

@@ -133,6 +133,26 @@ automatically unless your composer.json pins `itools/smartstring` lower.*
 >
 > Regex: `->(where|whereNot|contains)\([^)]*(null|true|false)\s*\)`
 
+### Row-only methods throw on mixed arrays
+
+> `where()`, `whereNot()`, `whereInList()`, `sortBy()`, `indexBy()`,
+> `groupBy()`, `column()`, and `columnAt()` now require every element to be
+> a row. An array mixing rows and scalar values throws
+> `InvalidArgumentException` naming the element, instead of silently
+> skipping the scalars:
+>
+> ```php
+> $data = SmartArrayHtml::new(['count' => 5, 'items' => [['id' => 1]]]);
+> $data->where('id', 1);  // before: returned 0-1 rows, 'count' silently ignored
+>                         // after:  throws "where(): Expected a nested array of
+>                         //         rows, but element 'count' is not a row (int)"
+> ```
+>
+> Database results and empty arrays are unaffected - this only fires on
+> hand-built arrays that mix shapes. The error usually means the array was
+> wrapped one level too high (`->items` was the intended collection) or a
+> scalar was assigned onto a result set.
+
 ### Silent changes
 
 > - `print_r()` and `var_dump()` show just the array data, like dumping a

docs/ai-reference.md

@@ -237,8 +237,10 @@ the new collection.
 
 ## Filtering and Sorting
 
-All return a new collection; nested-only methods throw
-`InvalidArgumentException` on flat arrays and vice versa.
+All return a new collection; nested-only methods require every element to be
+a row and throw `InvalidArgumentException` on flat arrays or on mixed arrays
+where an element is not a row (empty arrays pass); flat-only methods likewise
+throw on nested input.
 
 | Method                                                     | Behavior                                                                                                                                                                |
 |------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------|

src/SmartArrayBase.php

@@ -591,7 +591,7 @@ public function sort(int $flags = SORT_REGULAR): static
 
     /**
      * Returns a new SmartArray sorted ascending by the specified field.
-     * Only works on nested arrays (throws on flat).
+     * Works on arrays of rows only: throws if the array is flat or any element is not a row.
      *
      * Rows missing the field sort first: the missing value counts as null for
      * ordering only (like MySQL ORDER BY), and rows are returned unchanged.
@@ -616,7 +616,7 @@ public function sortBy(string $field, int $flags = SORT_REGULAR): static
         }
         $this->warnIfMissing($field);
 
-        // sort by field value, treating missing fields as null (?? also covers non-array rows in mixed data)
+        // sort by field value, treating missing fields as null
         $sorted      = $this->toArray();
         $fieldValues = array_map(fn($row) => $row[$field] ?? null, $sorted);
         array_multisort($fieldValues, SORT_ASC, $flags, $sorted);
@@ -665,7 +665,7 @@ 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).
+     * Works on arrays of rows only: throws if the array is flat or any element is not a row.
      *
      * How values match:
      * - Numbers match numeric strings: where('id', 5) matches '5', where('price', 1) matches '1.00'
@@ -698,7 +698,7 @@ public function where(array|string $field, mixed $value = null): static
             // change one copy, change all four.
             $matches = [];
             foreach ($this->toArray() as $key => $row) {
-                if (is_array($row) && !empty($row[$field])) {
+                if (!empty($row[$field])) {
                     $matches[$key] = $row;
                 }
             }
@@ -713,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) && self::valueMatches($row[$field], $value)) {
+                if (array_key_exists($field, $row) && self::valueMatches($row[$field], $value)) {
                     $matches[$key] = $row;
                 }
             }
@@ -767,7 +767,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) && empty($row[$field])) {
+                if (empty($row[$field])) {
                     $matches[$key] = $row;
                 }
             }
@@ -779,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) || !self::valueMatches($row[$field], $value))) {
+            if (!array_key_exists($field, $row) || !self::valueMatches($row[$field], $value)) {
                 $matches[$key] = $row;
             }
         }
@@ -928,9 +928,6 @@ public function indexBy(string $field): static
         // Index by field; rows with a null or missing value index under '' (duplicates: last wins)
         $values = [];
         foreach ($this->toArray() as $row) {
-            if (!is_array($row)) {
-                continue; // scalar rows have no fields to index by
-            }
             $key          = $row[$field] ?? '';
             $key          = is_bool($key) ? (int)$key : (string)$key; // string cast keeps float precision; ints re-key as ints, bools as 1/0
             $values[$key] = $row;
@@ -981,9 +978,6 @@ public function groupBy(string $field): static
 
         $values = [];
         foreach ($this->toArray() as $row) {
-            if (!is_array($row)) {
-                continue; // scalar rows have no fields to group by
-            }
             $key            = $row[$field] ?? '';
             $key            = is_bool($key) ? (int)$key : (string)$key; // string cast keeps float precision; ints re-key as ints, bools as 1/0
             $values[$key][] = $row;
@@ -1016,9 +1010,6 @@ public function columnAt(int $index): static
 
         $values = [];
         foreach ($this->toArray() as $row) {
-            if (!is_array($row)) {
-                continue; // scalar rows have no columns to extract
-            }
             $count    = count($row);
             $rowIndex = ($index < 0) ? $count + $index : $index; // Convert negative indexes to positive
 
@@ -1572,17 +1563,35 @@ private function assertFlatArray(): void
     }
 
     /**
-     * Assert that array has at least one nested array in values.
+     * Assert that every element is a row (nested array). Empty arrays pass, so
+     * empty result sets flow through row-only methods without error.
      *
-     * @throws InvalidArgumentException If the array is flat.
+     * Row-only methods can rely on every element being a child SmartArray, so
+     * their loops don't need per-row is_array() checks.
+     *
+     * @throws InvalidArgumentException If the array is flat or contains non-row elements.
      */
     private function assertNestedArray(): void
     {
-        if (!empty($this->data) && $this->isFlat()) {
-            $function = debug_backtrace(DEBUG_BACKTRACE_IGNORE_ARGS, 2)[1]['function'];
-            $error    = "$function(): Expected a nested array, but got a flat array";
-            throw new InvalidArgumentException($error);
+        // Construction and writes maintain rowsOnly, so result sets pass in O(1)
+        if ($this->rowsOnly) {
+            return;
+        }
+
+        // rowsOnly false means a scalar was stored at some point, but an unset may
+        // have removed it since, so scan to see what's really here
+        foreach ($this->data as $key => $value) {
+            if (!$value instanceof self) {
+                $function = debug_backtrace(DEBUG_BACKTRACE_IGNORE_ARGS, 2)[1]['function'];
+                $error    = $this->isNested()
+                    ? "$function(): Expected a nested array of rows, but element '$key' is not a row (" . get_debug_type($value) . ")"
+                    : "$function(): Expected a nested array, but got a flat array";
+                throw new InvalidArgumentException($error);
+            }
         }
+
+        // All rows after all: the flag went stale-false after an unset, set it right
+        $this->rowsOnly = true;
     }
 
     /**
@@ -1591,8 +1600,6 @@ private function assertNestedArray(): void
      * names, so a miss there is almost always a typo. Everywhere else (lookup maps
      * from indexBy()/column(), standalone arrays) keys are data, a miss is a normal
      * no-match, and the access renders blank silently.
-     * Skipped for method-argument checks on mixed data (scalar config + array fields)
-     * since there's no first row to check against.
      *
      * @param string|int $key      The key to check for
      * @param bool       $isOffset True for key access ($array->key), false for method args (where, sortBy, etc.)
@@ -1611,7 +1618,7 @@ private function warnIfMissing(string|int $key, bool $isOffset = false): void
         if (!$isOffset) {
             $first = $this->first();
             if (!($first instanceof self)) {
-                return; // Non-uniform data (e.g., schemas with scalar config + array fields)
+                return; // empty array: first() returns SmartNull, no row to sample
             }
             $target = $first;
         }

tests/Unit/FilterUniqueSortTest.php

@@ -221,6 +221,17 @@ public function testSortByOnFlatThrows(string $class): void
         $class::new(['a', 'b'])->sortBy('name');
     }
 
+    #[DataProvider('modeProvider')]
+    public function testSortByThrowsOnScalarRows(string $class): void
+    {
+        $sa = $class::new(['tableName' => 'users', 'fields' => ['a' => 1]]);
+
+        $this->expectException(InvalidArgumentException::class);
+        $this->expectExceptionMessage("sortBy(): Expected a nested array of rows, but element 'tableName' is not a row (string)");
+
+        $sa->sortBy('a');
+    }
+
     #[DataProvider('modeProvider')]
     public function testSortByRejectsDirectionConstants(string $class): void
     {

tests/Unit/ProjectionTest.php

@@ -119,12 +119,14 @@ public function testPluckNthOnFlatThrows(string $class): void
     }
 
     #[DataProvider('modeProvider')]
-    public function testColumnAtSkipsScalarRows(string $class): void
+    public function testColumnAtThrowsOnScalarRows(string $class): void
     {
-        // One array value makes the array "nested"; scalar rows have no columns to extract
         $sa = $class::new([['a', 'b'], 'scalar', ['c', 'd']]);
 
-        $this->assertSame(['a', 'c'], $sa->columnAt(0)->toArray());
+        $this->expectException(InvalidArgumentException::class);
+        $this->expectExceptionMessage("columnAt(): Expected a nested array of rows, but element '1' is not a row (string)");
+
+        $sa->columnAt(0);
     }
 
     //endregion
@@ -240,18 +242,14 @@ public function testIndexByFloatAndBoolKeys(string $class): void
     }
 
     #[DataProvider('modeProvider')]
-    public function testIndexBySkipsScalarRows(string $class): void
+    public function testIndexByThrowsOnScalarRows(string $class): void
     {
-        // One array value makes the array "nested"; scalar rows have no fields to index by
         $sa = $class::new([['id' => 1, 'n' => 'a'], 'scalar', ['id' => 2, 'n' => 'b']]);
 
-        [$result, $output] = $this->captureOutput(fn() => $sa->indexBy('id'));
+        $this->expectException(InvalidArgumentException::class);
+        $this->expectExceptionMessage("indexBy(): Expected a nested array of rows, but element '1' is not a row (string)");
 
-        $this->assertSame([
-            1 => ['id' => 1, 'n' => 'a'],
-            2 => ['id' => 2, 'n' => 'b'],
-        ], $result->toArray());
-        $this->assertSame('', $output);
+        $sa->indexBy('id');
     }
 
     //endregion
@@ -335,15 +333,14 @@ public function testGroupByFloatAndBoolKeys(string $class): void
     }
 
     #[DataProvider('modeProvider')]
-    public function testGroupBySkipsScalarRows(string $class): void
+    public function testGroupByThrowsOnScalarRows(string $class): void
     {
-        // One array value makes the array "nested"; scalar rows have no fields to group by
         $sa = $class::new([['g' => 'a', 'v' => 1], 'scalar', ['g' => 'a', 'v' => 2]]);
 
-        [$result, $output] = $this->captureOutput(fn() => $sa->groupBy('g'));
+        $this->expectException(InvalidArgumentException::class);
+        $this->expectExceptionMessage("groupBy(): Expected a nested array of rows, but element '1' is not a row (string)");
 
-        $this->assertSame(['a' => [['g' => 'a', 'v' => 1], ['g' => 'a', 'v' => 2]]], $result->toArray());
-        $this->assertSame('', $output);
+        $sa->groupBy('g');
     }
 
     //endregion

tests/Unit/WarningsTest.php

@@ -188,18 +188,6 @@ public function testArgumentWarningSkippedOnEmptyArray(string $class): void
         $this->assertSame('', $output, 'an empty array has no rows to check the field against');
     }
 
-    #[DataProvider('modeProvider')]
-    public function testArgumentWarningSkippedWhenFirstElementIsNotARow(string $class): void
-    {
-        // Mixed data (scalar config keys alongside array fields) has no first row
-        // to sample, so the check is skipped rather than reporting a false miss
-        $mixed = $class::new(['tableName' => 'users', 'fields' => ['a' => 1]]);
-
-        [, $output] = $this->captureOutput(fn() => $mixed->sortBy('zzz'));
-
-        $this->assertSame('', $output);
-    }
-
     #[DataProvider('modeProvider')]
     public function testMissingFieldWarningIsAlsoSentToErrorHandlers(string $class): void
     {

tests/Unit/WhereTest.php

@@ -142,19 +142,66 @@ public function testWhereAndWhereNotPartitionForEveryValueType(string $class): v
     }
 
     #[DataProvider('modeProvider')]
-    public function testWhereExcludesRowsMissingFieldAndNonArrayRows(string $class): void
+    public function testWhereExcludesRowsMissingField(string $class): void
     {
         $sa = $class::new([
-            'config' => 'scalar row',
-            'a'      => ['f' => 5],
-            'b'      => ['other' => 5],
+            'a' => ['f' => 5],
+            'b' => ['other' => 5],
         ]);
 
         [$result, ] = $this->captureOutput(fn() => $sa->where('f', 5));
 
         $this->assertSame(['a' => ['f' => 5]], $result->toArray());
     }
 
+    #[DataProvider('modeProvider')]
+    public function testWhereThrowsOnScalarRows(string $class): void
+    {
+        $sa = $class::new(['config' => 'scalar', 'a' => ['f' => 5]]);
+
+        $this->expectException(InvalidArgumentException::class);
+        $this->expectExceptionMessage("where(): Expected a nested array of rows, but element 'config' is not a row (string)");
+
+        $sa->where('f', 5);
+    }
+
+    #[DataProvider('modeProvider')]
+    public function testWhereNotThrowsOnScalarRows(string $class): void
+    {
+        $sa = $class::new(['config' => 'scalar', 'a' => ['f' => 5]]);
+
+        $this->expectException(InvalidArgumentException::class);
+        $this->expectExceptionMessage("whereNot(): Expected a nested array of rows, but element 'config' is not a row (string)");
+
+        $sa->whereNot('f', 5);
+    }
+
+    #[DataProvider('modeProvider')]
+    public function testWhereInListThrowsOnScalarRows(string $class): void
+    {
+        $sa = $class::new(['config' => 'scalar', 'a' => ['tags' => "\tred\t"]]);
+
+        $this->expectException(InvalidArgumentException::class);
+        $this->expectExceptionMessage("whereInList(): Expected a nested array of rows, but element 'config' is not a row (string)");
+
+        $sa->whereInList('tags', 'red');
+    }
+
+    #[DataProvider('modeProvider')]
+    public function testWhereWorksAgainAfterScalarRowIsUnset(string $class): void
+    {
+        // Storing a scalar marks the array as not rows-only, and unset doesn't clear
+        // the mark - the assert rescans, proves all remaining elements are rows, and passes
+        $sa = $class::new(['config' => 'scalar', 'a' => ['f' => 5], 'b' => ['f' => 0]]);
+
+        [$result, ] = $this->captureOutput(function () use ($sa) {
+            unset($sa['config']); // bracket unset echoes a deprecation, not under test here
+            return $sa->where('f', 5);
+        });
+
+        $this->assertSame(['a' => ['f' => 5]], $result->toArray());
+    }
+
     #[DataProvider('modeProvider')]
     public function testWhereUnwrapsSmartStringValues(string $class): void
     {