fix: encode diagnostic keys, exit codes, and six smaller issues from review

- Missing-key warnings and array-syntax deprecation notices HTML-encode
  the key before echoing it. With a dynamic key like ->get($_GET['sort'])
  a key containing HTML reached the browser unencoded - a reflected XSS
  vector. The trigger_error() copy carries the same encoded key.
- or404() exits with status 1 like orDie(), so shell scripts and cron
  jobs see the failure. Output is unchanged.
- json_encode() also substitutes malformed UTF-8 in keys with U+FFFD,
  not just values - one corrupt byte in a key no longer returns false
  and loses the whole document.
- Array-syntax deprecation notices suggest one replacement style for
  reads, isset(), and unset(): ->key, ->{0}, ->{'users.id'}. Reads used
  to suggest ->get(0) while existence checks suggested ->{0}, so one
  empty() call printed two notices with different advice. Null and ''
  keys suggest ->get('') since ->{''} is a fatal error.
- debug(1) prints closures and other objects as their type instead of
  throwing Unsupported type: Closure - which fired on exactly the
  arrays that have a load handler, the ones debug exists to inspect.
- SmartNull->help() wraps in <xmp> when no Content-Type header is set,
  same rule as every other help() and debug(). It previously required
  an explicit text/html header, so typical pages got collapsed text.
- filter() phpdoc notes keys are preserved like array_filter() and
  shows ->values() as the reindex step before json_encode().

Also: settled all remaining REVIEW comments in the test suite - each
now states the ruled behavior and why (load() record-set guard, filter
keys, conversion root pointer, nested isset noise, SmartNull error
class names, docs coverage).

Author: daveedis

CHANGELOG.md

@@ -6,6 +6,10 @@
 
 ## [Unreleased]
 
+### Security
+- Missing-key warnings and array-syntax deprecation notices HTML-encode the key before echoing it. With a dynamic key (`->get($_GET['sort'])`, `$arr[$_GET['sort']]`), a key containing HTML reached the browser unencoded - a reflected XSS vector. The `trigger_error()` copy carries the same encoded key.
+- `json_encode($smartArray)` also substitutes malformed UTF-8 in keys with � (U+FFFD), not just values - one corrupt byte in a key no longer makes it return false and lose the whole document.
+
 ### Added
 - `at($index)` - new name for `nth()`: get an element by position, zero-based, negative indices count from the end. Matches JavaScript's `Array.at()`. `get()` is by key, `at()` is by position.
 - `columnAt($index)` - new name for `pluckNth()`: get the column at a position from each row, ignoring key names. `column()` is by key, `columnAt()` is by position.
@@ -25,9 +29,10 @@
 - `SmartArray::new($data, true)` and `SmartArrayHtml::new($data, false)` now throw like the constructors do, instead of silently ignoring the boolean. Old code that passed `true` expecting auto-encoding was silently getting raw, unencoded values - now it fails at the call site with the class to use instead. Redundant booleans (`false` on SmartArray, `true` on SmartArrayHtml) log a deprecation and proceed.
 - `sortBy()` second parameter renamed `$type` → `$flags` - it always held PHP sort flags, and now matches `sort()` and PHP's own sort functions. Affects named-argument calls only: `sortBy('name', flags: SORT_NATURAL)`.
 - `column(null)` and `column(null, null)` now match PHP's `array_column()`: whole rows renumbered from 0, instead of throwing "unexpected arguments"
+- Array-syntax deprecation notices suggest one replacement style for reads, `isset()`, and `unset()`: `->key` for property-safe names, `->{0}` for integer keys, `->{'users.id'}` for other keys (`->get()` also works for reads). Reads used to suggest `->get(0)` while existence checks suggested `->{0}`, so one `empty()` call printed two notices with different advice. Null and `''` keys suggest `->get('')` - the brace form is a fatal error for an empty property name.
 - `isset($array['key'])` and `empty($array['key'])` now follow `$onOffsetAccess` like reads, writes, and `unset()` - notice by default, exception in `'throw'` mode. Existence checks were the one silent form of the deprecated `[]` syntax; if `[]` support is removed in a future version, `isset()` on the object would silently return false instead of erroring, so these call sites need migrating with the rest. Property-syntax checks (`isset($array->key)`) are unaffected and stay signal-free. Internal existence checks now call `array_key_exists()` directly, removing two method calls from every `get()`.
 - `or404()` outputs `<html>` instead of `<html lang>` - an empty `lang` reads as an invalid value to accessibility checkers, and the message language is caller-supplied so it can't be declared. Matches SmartString.
-- `orDie()` now exits with status 1 instead of 0, so shell scripts and cron jobs see the failure. Output is unchanged. Matches SmartString.
+- `orDie()` and `or404()` now exit with status 1 instead of 0, so shell scripts and cron jobs see the failure. Output is unchanged. Matches SmartString.
 - Developer-mistake exceptions (bad types, wrong context, misuse) now throw `CallerException`, which reports your file and line instead of the library's internals - the same class SmartString uses. It extends `InvalidArgumentException`, so existing catch blocks keep working, except six throws that previously used `RuntimeException`: `load()` misuse (no handler, non-callable handler, bad or empty field name, called on a record set), `orRedirect()` after headers sent, and writing to a `SmartNull`. See UPGRADING.md. `orThrow()` still throws `RuntimeException` by contract.
 - Clearer messages for two of those throws: `load()` with no handler now explains handlers come from the database layer (was "No loadHandler property is defined"), and writing to a `SmartNull` now says the value came from a missing key or empty result (was "Cannot set values on SmartNull"). The unsupported-type message from `set()` no longer prefixes the library's internal method name.
 - Unknown methods on `SmartNull` now throw the same `Error` as the rest of the library - method name, "did you mean" hint, caller's file and line - instead of `InvalidArgumentException("Method 'x' not found")`. Chains from a missing key now fail with the same message quality as everything else.
@@ -44,6 +49,8 @@
 - `setLoadHandler()` - the handler is passed as the `loadHandler` constructor property, which is how the database layer (ZenDB) has always set it. The setter had no known callers, and it couldn't work on record sets anyway: rows are built during construction and snapshot the handler at that moment, so a handler set afterward never reached them.
 
 ### Fixed
+- `SmartNull->help()` wraps its output in `<xmp>` when no Content-Type header is set, same rule as every other `help()` and `debug()` - PHP's default response type is text/html. Previously it only wrapped when text/html was explicitly set via `header()`, so on typical pages (which never call `header()`) it printed as collapsed, unformatted text.
+- `debug(1)` no longer throws `Unsupported type: Closure` on arrays with a load handler - exactly the database results it exists to inspect. Callables and other objects in the properties block print as their type (`Closure,`) instead.
 - `get($key, $default)` defaults now act like stored values: Smart defaults (SmartString, SmartArray, SmartNull) unwrap and re-wrap for the array's mode. Previously a SmartNull default threw `InvalidArgumentException`, and cross-mode Smart defaults (a SmartString default on SmartArray, a raw SmartArray default on SmartArrayHtml) threw `TypeError` from the return declarations.
 - `sortBy()` no longer throws a bare `ValueError: Array sizes are inconsistent` when a row is missing the sort field. Missing fields sort first (treated as null for ordering, like MySQL ORDER BY); rows are returned unchanged.
 - `indexBy()` no longer gives rows missing the index field a leftover numeric key that looks like a real field value. Null and missing values now both index under `''` (matching how null field values were already handled), duplicates last-wins.

src/DeprecatedAliases.php

@@ -357,28 +357,30 @@ public function offsetUnset(mixed $offset): void
      */
     private function triggerArrayAccessDeprecation(mixed $key, string $operation = 'get'): void
     {
+        // SECURITY: the key can be user input (e.g. $arr[$_GET['sort']]) and 'notify' mode echoes
+        // the message into the page, so encode it. $key is display-only from here on; the actual
+        // data access already happened with the original key.
+        if (is_string($key)) {
+            $key = htmlspecialchars($key, self::HTML_ENCODE_FLAGS, 'UTF-8');
+        }
         $keyStr          = is_string($key) ? "'$key'" : (string) $key;
         $isValidPropName = is_string($key) && preg_match('/^[a-zA-Z_][a-zA-Z0-9_]*$/', $key);
 
         // Suggest the preferred access method. A null key only reaches 'set' via
-        // the append syntax `$arr[] = $value`; for 'unset'/'get' it indicates a
-        // programmer error that PHP itself treats as an empty-string key.
+        // the append syntax `$arr[] = $value`; for 'unset'/'get'/'exists' it indicates
+        // a programmer error that PHP itself treats as an empty-string key.
         $suggestion = match ($operation) {
             'set' => match (true) {
                 is_null($key)    => '->set($key, $value) using an explicit key',
                 is_int($key)     => "->set($key, \$value)",
                 $isValidPropName => "->$key = \$value",
                 default          => "->set('$key', \$value) or ->{'$key'} = \$value",
             },
-            'unset', 'exists' => match (true) {
-                is_int($key)     => '->{' . $key . '}',
-                $isValidPropName => "->$key",
-                default          => "->{'$key'}",
-            },
             default => match (true) {
-                is_int($key)     => "->get($key)",
-                $isValidPropName => "->$key",
-                default          => "->get('$key')",
+                is_int($key)                 => '->{' . $key . '}',
+                $isValidPropName             => "->$key",
+                $key === '' || $key === null => "->get('')", // PHP treats a null/'' key as key ''; ->{''} is a fatal "Cannot access empty property"
+                default                      => "->{'$key'}",
             },
         };
 

src/SmartArrayBase.php

@@ -479,8 +479,12 @@ public function unique(): static
      * objects, and should return true to keep the element, false to remove it.
      * When called without a callback, removes all falsy values (empty strings, 0, null, false).
      *
+     * Keys are preserved, like PHP's array_filter(), so a filtered list json_encodes as an
+     * object ({"0":...,"2":...}) - chain ->values() first to reindex and get a JSON array.
+     *
      *     $active   = $users->filter(fn($row) => $row['status'] === 'active');
      *     $nonEmpty = $values->filter();
+     *     $json     = json_encode($values->filter()->values());  // reindex for a JSON array
      *
      * @param callable|null $callback A function($value, $key) that returns true to keep, false to remove.
      * @return static A new SmartArray containing only the elements that passed the test.
@@ -1118,7 +1122,9 @@ private static function prettyPrintR(mixed $var, int $debugLevel = 0, int $depth
             $varExport = 'SmartNull()';
             $output    = str_pad("$keyPrefix$varExport,", $commentOffset) . "$comment\n";
         } else {
-            throw new RuntimeException("Unsupported type: $debugType");
+            // Anything else prints as its type, e.g. the loadHandler Closure in the
+            // debug(1) properties block - debug output describes, it never throws
+            $output = str_pad("$keyPrefix$debugType,", $commentOffset) . "$comment\n";
         }
 
         // Indent each line
@@ -1209,7 +1215,8 @@ public function __unset(string $name): void
     //region Error Handling
 
     /**
-     * Sends a 404 header and message if the array is empty, then exits.
+     * Sends a 404 header and message if the array is empty, then exits with status 1
+     * so shell scripts and cron jobs see the failure.
      *
      * @param string|null $text Plain-text message; HTML-encoded automatically before output. Defaults to "The requested URL was not found on this server."
      * @return static Returns $this if not empty, exits with 404 if empty
@@ -1238,7 +1245,7 @@ public function or404(?string $text = null): static
             </body>
             </html>
             __HTML__;
-        exit;
+        exit(1);
     }
 
     /**
@@ -1364,12 +1371,16 @@ private function warnIfMissing(string|int $key, string $warningType = 'argument'
         if (empty($target->data) || array_key_exists($key, $target->data)) {
             return;
         }
-        $caller           = self::getExternalCaller();
-        $keyOrEmptyQuotes = $key === "" ? "''" : $key; // Show empty quotes for empty string keys
+        $caller = self::getExternalCaller();
+
+        // SECURITY: the key can be user input (e.g. ->get($_GET['sort'])) and the warning echoes
+        // into the page, so encode it. The trigger_error() copy gets the same encoded key.
+        $keyDisplay       = is_string($key) ? htmlspecialchars($key, self::HTML_ENCODE_FLAGS, 'UTF-8') : $key;
+        $keyOrEmptyQuotes = $keyDisplay === "" ? "''" : $keyDisplay; // Show empty quotes for empty string keys
 
         $warning = match ($warningType) {
             'offset'   => "$keyOrEmptyQuotes is undefined in {$caller['file']}:{$caller['line']}\n",
-            'argument' => "{$caller['function']}(): '$key' doesn't exist\n",
+            'argument' => "{$caller['function']}(): '$keyDisplay' doesn't exist\n",
             default    => throw new InvalidArgumentException("Invalid warning type '$warningType'"),
         };
 
@@ -1478,18 +1489,23 @@ public function getIterator(): Iterator
      * 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.
+     * Substitutes malformed UTF-8 in keys and values with � (U+FFFD) so json_encode($smartArray)
+     * returns valid JSON instead of false. Nested SmartArrays scrub themselves when json_encode()
+     * descends into them.
      *
      * @return array The internal data array.
      */
     public function jsonSerialize(): array
     {
-        $data = $this->data;
-        foreach ($data as $key => $value) {
-            if (is_string($value) && preg_match('//u', $value) !== 1) { // isMalformed: ~5x faster than mb_check_encoding()
-                $data[$key] = json_decode(json_encode($value, JSON_INVALID_UTF8_SUBSTITUTE)); // json_encode's own U+FFFD substitution
+        $data = [];
+        foreach ($this->data as $key => $value) {
+            if (is_string($key) && preg_match('//u', $key) !== 1) { // isMalformed: ~5x faster than mb_check_encoding()
+                $key = json_decode(json_encode($key, JSON_INVALID_UTF8_SUBSTITUTE)); // json_encode's own U+FFFD substitution
+            }
+            if (is_string($value) && preg_match('//u', $value) !== 1) {
+                $value = json_decode(json_encode($value, JSON_INVALID_UTF8_SUBSTITUTE));
             }
+            $data[$key] = $value;
         }
         return $data;
     }

src/SmartNull.php

@@ -101,7 +101,11 @@ public function help(): void
             the final result is accessed.
             __TEXT__;
 
-        $isHtmlOutput = stripos(implode("\n", headers_list()), 'text/html') !== false;
+        // Wrap in <xmp> for readability when output is (or will default to) HTML - same rule
+        // as SmartArrayBase::xmpWrap(): no Content-Type header means PHP sends its default text/html
+        $headersList  = implode("\n", headers_list());
+        $isHtmlOutput = !preg_match('|^\s*Content-Type:\s*|im', $headersList)
+                     || preg_match('|^\s*Content-Type:\s*text/html\b|im', $headersList);
         if ($isHtmlOutput) {
             $output = "<xmp>$output</xmp>";
         }

tests/Integration/DocsCoverageTest.php

@@ -51,7 +51,7 @@ final class DocsCoverageTest extends SmartArrayTestCase
      * the forward check so the rest of the guard still runs, and each one is a docs bug
      * waiting to be written, not a permanent exemption.
      */
-    // REVIEW: empty as of 2026-08-02 - every public method is documented in both files.
+    // Empty as of 2026-08-02: every public method is documented in both files.
     private const UNDOCUMENTED_TODAY = [];
 
     //endregion

tests/Integration/ProductionRecipesTest.php

@@ -311,9 +311,9 @@ public function testA12FilteredPluckKeepsOriginalKeys(string $class): void
             fn() => $tables->pluck('TABLE_NAME')->filter(fn($name) => str_starts_with($name, 'cms_'))->toArray(),
         );
 
-        // REVIEW: filter() keeps the source keys, so this "flat value list" comes back
-        // with a gap (0 and 2). json_encode() then emits an object instead of an array.
-        // Alternative: reindex in filter(), or document ->values() as the finisher here.
+        // filter() keeps source keys like array_filter(), so this value list comes back
+        // with a gap (0 and 2) and json_encode() would emit an object, not an array.
+        // Chain ->values() to reindex when that matters (noted in the filter() phpdoc).
         $this->assertSame([0 => 'cms_accounts', 2 => 'cms_orders'], $ours);
         $this->assertSame('', $output);
     }

tests/Unit/ConversionTest.php

@@ -423,16 +423,13 @@ public function testJsonSerializeReplacesMalformedUtf8WithReplacementCharacter(s
     }
 
     #[DataProvider('modeProvider')]
-    public function testJsonEncodeFailsOnMalformedUtf8Key(string $class): void
+    public function testJsonEncodeSubstitutesMalformedUtf8InKeys(string $class): void
     {
-        // REVIEW: the substitution covers values only, so one corrupt byte in a
-        // KEY still returns false and loses the whole document - the failure the
-        // value scrubbing exists to prevent. Keys come from column names, so this
-        // is rare, but jsonSerialize() could scrub them the same way.
+        // Keys scrub to U+FFFD like values, so one corrupt byte in a key can't
+        // make json_encode() return false and lose the whole document.
         $sa = $class::new(["caf\xE9" => 'value']);
 
-        $this->assertFalse(json_encode($sa));
-        $this->assertSame('Malformed UTF-8 characters, possibly incorrectly encoded', json_last_error_msg());
+        $this->assertSame('{"caf\\ufffd":"value"}', json_encode($sa));
     }
 
     //endregion