docs: document edge-case behavior found in test suite review

- contains() and unique() compare loosely - add the surprising cases to the
  docblocks ('1' matches 1 and true; '', false, and null count as duplicates)
- sortBy() reindexes numeric keys but keeps string keys (array_multisort
  default) - docs previously said all keys get reindexed
- json_encode() returns raw values, never HTML-encoded, even for SmartArrayHtml
- orRedirect() throws whenever headers are already sent, even with results -
  make the fail-fast explicit in the docblock
- debug() calls the load handler once per key - flag it so nobody debugs a row
  in a loop with a live database handler
- SmartNull is truthy and == '' - note how to check for it explicitly
- Reword load() error when the handler returns false: "doesn't support field"
  instead of "not available" (the handler exists and ran; it declined)
- CHANGELOG: isFirst()/isLast()/position() aren't deprecated - they were
  promoted back to first-class in 2.6.2; drop them from the stale deprecation
  line

Author: daveedis

CHANGELOG.md

@@ -55,7 +55,7 @@
 ### Deprecated
 - **Array access syntax**: `$array['key']` is deprecated - use `$array->key` or `$array->get('key')` instead
 - `SmartArrayRaw` class - now an alias for `SmartArray`, use `SmartArray` directly
-- `isFirst()`, `isLast()`, `position()`, `isMultipleOf()`, `chunk()`, `smartMap()` - now trigger deprecation notice
+- `isMultipleOf()`, `chunk()`, `smartMap()` - now trigger deprecation notice (isFirst/isLast/position were promoted back to first-class methods in 2.6.2)
 - `toRaw()` and `toHtml()` - use `asRaw()` and `asHtml()` instead
 
 ### Fixed

README.md

@@ -518,12 +518,12 @@ Note: All methods return a new `SmartArray` object unless otherwise specified.
 | Array Information     |                         count() | Get the number of elements                                                                                                   |
 |                       |                       isEmpty() | Returns true if array has no elements                                                                                        |
 |                       |                    isNotEmpty() | Returns true if array has any elements                                                                                       |
-|                       |                 contains(value) | Returns true if array contains value                                                                                         |
+|                       |                 contains(value) | Returns true if array contains value (loose == comparison)                                                                   |
 | Position & Layout     |                       isFirst() | Returns true if first element in parent array                                                                                |
 |                       |                        isLast() | Returns true if last element in parent array                                                                                 |
 |                       |                      position() | Gets position in parent array (starting from 1)                                                                              |
 | Sorting & Filtering   |                          sort() | Sorts elements by value (flat arrays only)                                                                                   |
-|                       |                   sortBy(field) | Sorts rows by field value (nested arrays only)                                                                               |
+|                       |                   sortBy(field) | Sorts rows by field value (nested arrays only; numeric keys reindexed, string keys preserved)                                |
 |                       |                        unique() | Removes duplicate values (flat arrays only)                                                                                  |
 |                       |                        filter() | Removes falsey values ("", 0, empty array, etc)                                                                              |
 |                       |                filter(callback) | Removes elements where callback returns false (callback receives raw values)                                                 |

src/SmartArrayBase.php

@@ -433,7 +433,11 @@ public function isNotEmpty(): bool
     }
 
     /**
-     * Check if array contains a specific value (loose comparison).
+     * Check if array contains a specific value (loose == comparison).
+     *
+     * 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).
      */
     public function contains(mixed $value): bool
     {
@@ -459,6 +463,9 @@ 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).
+     *
+     * Numeric row keys are re-indexed; string keys are preserved
+     * (array_multisort() default behavior).
      */
     public function sortBy(string $field, int $type = SORT_REGULAR): static
     {
@@ -477,6 +484,9 @@ public function sortBy(string $field, int $type = SORT_REGULAR): static
      * Returns a new SmartArray with duplicate values removed, keeping only the first
      * occurrence of each unique value, and preserving keys.
      * Only works on flat arrays (throws on nested).
+     *
+     * Values are compared as strings (array_unique() default): 1, '1', and true
+     * count as duplicates; '', false, and null count as duplicates of each other.
      */
     public function unique(): static
     {
@@ -1046,7 +1056,7 @@ public function load(string $field): static|SmartNull
         // get handler output
         $result = $loadHandler($this, $field);
         if ($result === false) {
-            throw new Error("Load handler not available for '$field'\n" . self::occurredInFile());
+            throw new Error("Load handler doesn't support field '$field'\n" . self::occurredInFile());
         }
 
         // output error checking
@@ -1111,6 +1121,9 @@ public function help(): void
     /**
      * Displays diagnostic output: array contents, mysqli metadata, and object properties.
      *
+     * If a load handler is set, calls it for every key to annotate loadable
+     * relations - with a database-backed handler this can run one query per key.
+     *
      * @param int $debugLevel 0 for compact, 1+ for verbose with type info and object IDs
      */
     public function debug(int $debugLevel = 0): void
@@ -1379,7 +1392,9 @@ public function orThrow(string $text): static
      * Redirects to a URL if the array is empty
      *
      * Uses a simple Location header redirect (HTTP 302 Temporary Redirect).
-     * If headers have already been sent, this method will throw an exception.
+     * If headers have already been sent, throws immediately - even when the
+     * array is not empty - so a misplaced call fails on every request, not
+     * just when a result happens to be empty.
      *
      * @param string $url The URL to redirect to if array is empty
      * @return static Returns $this for method chaining if not empty, redirects if empty
@@ -1561,6 +1576,9 @@ public function getIterator(): Iterator
      * Returns serializable data for `json_encode()` via JsonSerializable.
      * Returns the raw internal array so nested SmartArrays serialize as plain arrays.
      *
+     * Values are raw, not HTML-encoded, even for SmartArrayHtml: JSON is a data
+     * format, and HTML encoding applies only when values are output as HTML.
+     *
      * Substitutes malformed UTF-8 with � (U+FFFD) so json_encode($smartArray) returns valid JSON
      * instead of false. Nested SmartArrays scrub themselves when json_encode() descends into them.
      *

src/SmartNull.php

@@ -15,6 +15,10 @@
  *
  * Implements SmartBase so instanceof SmartBase works for all Smart* types.
  * Extends stdClass to avoid IDE warnings related to undefined properties.
+ *
+ * Note: as an object, SmartNull is truthy in conditionals and compares loosely
+ * equal to '' via __toString ($smartNull == '' is true). For explicit checks
+ * use ->value() === null or instanceof SmartNull.
  */
 class SmartNull extends stdClass implements SmartBase, Iterator, ArrayAccess, JsonSerializable, Countable
 {

src/help.txt

@@ -62,7 +62,7 @@ Array Information
 ->count()               Get the number of elements
 ->isEmpty()             Returns true if array has no elements
 ->isNotEmpty()          Returns true if array has any elements
-->contains(value)       Check if array contains a specific value
+->contains(value)       Check if array contains a specific value (loose == comparison)
 
 Position & Layout
 ------------------
@@ -73,7 +73,7 @@ Position & Layout
 Sorting & Filtering
 --------------------
 ->sort()                      Sort elements by value, reindexing keys
-->sortBy(field)               Sort nested array by field value, reindexing keys
+->sortBy(field)               Sort nested array by field value (numeric keys reindexed, string keys preserved)
 ->sortBy(field, type)         Sort with type: SORT_STRING, SORT_NUMERIC, SORT_REGULAR (default)
 ->unique()                    Remove duplicate values, keeping first occurrence
 ->filter(callback)            Keep elements where callback returns true, using raw values

tests/Methods/LoadTest.php

@@ -187,7 +187,7 @@ public function testLoadThrowsWhenHandlerReturnsFalse(): void
         $smartArray->setLoadHandler(fn($row, $col) => false);
 
         $this->expectException(Error::class);
-        $this->expectExceptionMessage("Load handler not available for 'products'");
+        $this->expectExceptionMessage("Load handler doesn't support field 'products'");
 
         $smartArray->load('products');
     }