Merge branch 'main' into doc-review

Author: lucia

CHANGELOG.md

@@ -87,9 +87,10 @@ the docs - IDEs show a strikethrough with the replacement.
 - **`isset()`, `empty()`, and `??` treat a stored NULL as missing** -
   matching plain PHP arrays, so `??` fallbacks now fire on NULL columns.
   See [UPGRADING.md](UPGRADING.md)
-- **Row-only methods throw on mixed arrays** - a scalar next to rows
-  (usually a wrapped API response) throws instead of being silently
-  skipped; database results are unaffected. See
+- **Row-only methods ignore non-row elements** - `where()`, `sortBy()`,
+  `indexBy()`, and the other row-only methods keep the rows and skip
+  scalars next to them (each method handled that mix differently before);
+  a non-empty array with no rows still throws. See
   [UPGRADING.md](UPGRADING.md)
 - **`SmartArray::new($data, true)` throws** - a boolean that contradicts
   the class was silently ignored, returning raw values where HTML-safe

UPGRADING.md

@@ -150,25 +150,33 @@ automatically unless your composer.json pins `itools/smartstring` lower.*
 > Convert the field to a string first: `CAST(price AS CHAR)` in SQL, or
 > format it in PHP before keying.
 
-### Row-only methods throw on mixed arrays
+### Row-only methods ignore non-row elements
 
 > `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:
+> `groupBy()`, `column()`, and `columnAt()` now follow one rule: they work
+> on the rows (elements that are arrays) and ignore other elements. A
+> non-empty array with no rows throws `InvalidArgumentException`, same
+> as before; an empty array returns an empty result.
+>
+> In v2.x each method handled a scalar next to rows differently: the
+> `where()` family already skipped scalars (unchanged), `sortBy()` sorted
+> them in with the rows, and `indexBy()`, `groupBy()`, and `column()` kept
+> them under renumbered integer keys:
 >
 > ```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)"
+> $schema = SmartArray::new([
+>     'menuName' => 'Products',                          // scalar setting
+>     'name'     => ['type' => 'textfield', 'order' => 2],
+>     'photo'    => ['type' => 'upload',    'order' => 1],
+> ]);
+> $schema->where('type', 'upload');  // rows whose type matches; the scalar is ignored
+> $schema->indexBy('type');          // v2.x: scalars kept under renumbered keys; v3.0: rows only
 > ```
 >
-> 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.
+> Database results are unaffected - every element is a row. Review only
+> hand-built arrays that mix scalars and rows: a scalar that used to reach
+> the result through `sortBy()`, `indexBy()`, `groupBy()`, or `column()`
+> is left out now.
 
 ### Silent changes
 

composer.json

@@ -26,7 +26,8 @@
     },
     "autoload-dev": {
         "psr-4": {
-            "Itools\\SmartArray\\Tests\\": "tests/"
+            "Itools\\SmartArray\\Tests\\": "tests/",
+            "Itools\\Standards\\": "tests/Integration/"
         }
     },
     "config": {

docs/ai-reference.md

@@ -236,29 +236,32 @@ the new collection.
 
 ## Filtering and Sorting
 
-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.
+All return a new collection. Methods marked "Rows only" work on the rows
+(elements that are arrays) and ignore other elements (scalars/null); a
+non-empty array with no rows throws `InvalidArgumentException`
+(empty arrays pass). Methods marked "Flat only" throw on nested input.
 
 | Method                                                     | Behavior                                                                                                                                                                |
 |------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `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 |
+| `where(string $field, mixed $value = null): static`        | Rows 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`     | Rows 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`         | Rows 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"`, 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)  |
-| `sortBy(string $field, int $flags = SORT_REGULAR): static` | Nested only. Ascending by `$field`; rows missing the field sort first (like MySQL ORDER BY) and are kept unchanged. Numeric row keys renumber, string keys preserved. `SORT_NATURAL` for human number order; `SORT_ASC`/`SORT_DESC` throw |
+| `sortBy(string $field, int $flags = SORT_REGULAR): static` | Rows only. Ascending by `$field`; rows missing the field sort first (like MySQL ORDER BY) and are kept unchanged. Numeric row keys renumber, string keys preserved. `SORT_NATURAL` for human number order; `SORT_ASC`/`SORT_DESC` throw |
 | `unique(): static`                                         | Flat only. Removes duplicates keeping the first, keys preserved; compares as strings (`array_unique()`), so 1 and `'1'` are duplicates                                  |
 
 ## Transforming and Grouping
 
+"Rows only" and "Flat only" carry the same contract as in Filtering and
+Sorting above.
+
 | Method                                                                             | Behavior                                                                                                                     |
 |------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------|
-| `column(int\|string\|null $columnKey, int\|string\|null $indexKey = null): static` | Like `array_column()`: one field per row; `$indexKey` keys results by another field using `indexBy()` rules (missing field keys under `''`, floats throw, bools key as 1/0); `column(null, $indexKey)` keys whole rows, same as `indexBy()` |
-| `columnAt(int $index): static`                                                     | The column at a position from each row, ignoring key names (0 first, -1 last)                                                |
-| `indexBy(string $field): static`                                                   | Whole rows keyed by `$field`; duplicate keys keep the LAST row. Null/missing field keys under `''`; floats throw (convert to strings first), booleans key as 1/0 |
-| `groupBy(string $field): static`                                                   | Rows grouped by `$field`: one child collection per distinct value; same keying rules as `indexBy()`                          |
+| `column(int\|string\|null $columnKey, int\|string\|null $indexKey = null): static` | Rows only. Like `array_column()`: one field per row; `$indexKey` keys results by another field using `indexBy()` rules (missing field keys under `''`, floats throw, bools key as 1/0); `column(null, $indexKey)` keys whole rows, same as `indexBy()` |
+| `columnAt(int $index): static`                                                     | Rows only. The column at a position from each row, ignoring key names (0 first, -1 last)                                     |
+| `indexBy(string $field): static`                                                   | Rows only. Whole rows keyed by `$field`; duplicate keys keep the LAST row. Null/missing field keys under `''`; floats throw (convert to strings first), booleans key as 1/0 |
+| `groupBy(string $field): static`                                                   | Rows only. Rows grouped by `$field`: one child collection per distinct value; same keying rules as `indexBy()`                          |
 | `keys(): static`                                                                   | The keys as a new collection (encode on output in HTML mode)                                                                 |
 | `values(): static`                                                                 | The values, keys renumbered from 0                                                                                           |
 | `map(callable $callback): static`                                                  | New collection from `$callback` per element: closures receive raw `($value, $key)`, PHP built-ins receive `$value` only; rows arrive as plain arrays; returned arrays become rows again |

src/Deprecations.php

@@ -110,7 +110,7 @@ public function help(): void
     #[Deprecated(reason: 'renamed to column()', replacement: '%class%->column()')]
     public function pluck(string|int $valueField, ?string $keyField = null): static
     {
-        $this->assertNestedArray(); // assert here so the error names pluck(), not column()
+        $this->rows(); // run the row check here so a flat-array error names pluck(), not column()
         return $this->column($valueField, $keyField);
     }
 
@@ -133,7 +133,7 @@ public function nth(int $index): static|SmartNull|SmartString|string|int|float|b
     #[Deprecated(reason: 'renamed to columnAt()', replacement: '%class%->columnAt()')]
     public function pluckNth(int $index): static
     {
-        $this->assertNestedArray(); // assert here so the error names pluckNth(), not columnAt()
+        $this->rows(); // run the row check here so a flat-array error names pluckNth(), not columnAt()
         return $this->columnAt($index);
     }