speed up construction 2.9x and foreach 1.2-1.3x

Construction: all-scalar rows (typical database rows) clone a shared
template child and assign their data in one copy-on-write step instead of
running the constructor and storing field by field. Mixed rows keep the
full conversion path.

foreach: getIterator() returns a C-level ArrayIterator when nothing needs
wrapping - raw mode, or when every value is a row, tracked by a rowsOnly
flag that flips false wherever a scalar or null is stored. HTML arrays
with scalar values keep the wrapping generator, so foreach yields
SmartStrings exactly as before.

25-row record set: 19.0 -> 6.6 microseconds to construct; a rendered
25-row list page now runs 1.15x vs hand-written htmlspecialchars code
(was 1.59x). Side effect: deprecated SmartArrayRaw logs its constructor
deprecation twice per result set (outer + row template) instead of once
per row.

Author: daveedis

CHANGELOG.md

@@ -32,7 +32,8 @@
 - Array-syntax deprecation notices suggest one replacement style across reads, writes, `isset()`, and `unset()`: `->key` and `->key = $value` for property-safe names, `->{0}` for integer keys, `->{'users.id'}` for other keys. Reads used to suggest `->get(0)` while existence checks suggested `->{0}`, so one `empty()` call printed two notices with different advice, and writes suggested the now-deprecated `->set()`. Null and `''` keys are the exception and suggest `->get('')` / `->set('', $value)` - 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()`.
 - `isset()`, `empty()`, and `??` treat a stored null as missing, matching plain PHP arrays: on a NULL column, `isset($row->field)` is now false and `$row->field ?? 'none'` returns `'none'`. Previously they answered "does the column exist", so in HTML mode `??` fallbacks never fired on NULL columns (the wrapped null echoed as `""`). Bracket syntax (`isset($row['field'])`) matches. Direct access is unchanged: `$row->field` still returns the stored null, wrapped in HTML mode, with no warning. Ask `$row->keys()->contains('field')` when you need "does the key exist, even if NULL". Note `??` substitutes its fallback before the library runs, so the fallback skips HTML encoding - use `->or()` for display fallbacks that carry user data. See UPGRADING.md.
-- Array construction is ~1.6x faster (local benchmark, 25-row record set: 19.0 → 11.9 microseconds). Three changes: internal properties assign from a fixed key list instead of `property_exists()` checks per key, child rows share one properties array instead of rebuilding it per row, and scalar values store directly in the constructor loop instead of dispatching through `setElement()`. The fixed key list also means constructor `$properties` can no longer name arbitrary internal properties like `$data` - unknown keys are ignored, same as before.
+- Array construction is ~2.9x faster (local benchmark, 25-row record set: 19.0 → 6.6 microseconds). Internal properties assign from a fixed key list instead of `property_exists()` checks per key; all-scalar rows (typical database rows) clone a shared template child and assign their data in one copy-on-write step instead of running the constructor and storing field by field; scalars store directly in the constructor loop instead of dispatching through `setElement()`. The fixed key list also means constructor `$properties` can no longer name arbitrary internal properties like `$data` - unknown keys are ignored, same as before. One visible side effect: deprecated `SmartArrayRaw` logs its constructor deprecation twice per result set (outer array + row template) instead of once per row.
+- `foreach` is 1.2-1.3x faster when nothing needs wrapping: `getIterator()` returns a C-level `ArrayIterator` in raw mode and for record sets where every value is a row, instead of stepping through a generator per element. HTML-mode arrays with scalar values keep the wrapping generator, so foreach yields SmartStrings exactly as before.
 - `help()` and `debug()` print plain text on the command line instead of wrapping output in literal `<xmp>` tags. Terminal detection checks `PHP_SAPI` plus two fallbacks (Windows console `SESSIONNAME`, missing `SCRIPT_NAME`) because some hosts' CGI builds misreport SAPI. Web responses are unchanged. Matches SmartString.
 - `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()` and `or404()` now exit with status 1 instead of 0, so shell scripts and cron jobs see the failure. Output is unchanged. Matches SmartString.

src/SmartArrayBase.php

@@ -5,7 +5,7 @@
 
 use stdClass;
 use Throwable, Error, RuntimeException;
-use ArrayAccess, IteratorAggregate, Iterator, Countable, JsonSerializable, Closure;
+use ArrayAccess, ArrayIterator, IteratorAggregate, Iterator, Countable, JsonSerializable, Closure;
 use Itools\SmartString\SmartString;
 
 /**
@@ -29,6 +29,15 @@ abstract class SmartArrayBase extends stdClass implements SmartBase, ArrayAccess
      */
     private array $data = [];
 
+    /**
+     * True while every value is a child SmartArray (or the array is empty), so
+     * getIterator() can skip SmartString wrapping and iterate the fast way.
+     * Storing a scalar or null sets this false, and nothing sets it back (an
+     * unset can leave it stale-false, which only means the slower,
+     * always-correct wrapping path).
+     */
+    private bool $rowsOnly = true;
+
     //endregion
     //region Position Properties
 
@@ -110,22 +119,41 @@ public function __construct(array $array = [], array $properties = [])
         $this->isLast          = $properties['isLast']          ?? false;
 
         // Add elements and set position metadata on child SmartArrays
-        $count      = count($array);
-        $position   = 0;
-        $childProps = null;
+        $count         = count($array);
+        $position      = 0;
+        $childTemplate = null;
         foreach ($array as $key => $value) {
             $position++;
 
             // Fast path: scalars and nulls, the bulk of real data (encoded on access by getElement)
             if (is_scalar($value) || $value === null) {
                 $this->data[$key] = $value;
+                $this->rowsOnly   = false;
                 continue;
             }
 
-            // Nested arrays become child rows; every child gets the same properties, so build the array once
+            // Nested arrays become child rows. The template child is built once and cloned
+            // per row (cheaper than running the constructor), and all-scalar rows - typical
+            // database rows - assign their data wholesale: a copy-on-write array assignment
+            // instead of a per-field loop.
             if (is_array($value)) {
-                $childProps      ??= $this->getInternalProperties();
-                $child             = new static($value, $childProps);
+                $childTemplate ??= new static([], $this->getInternalProperties());
+
+                $allScalar = true;
+                foreach ($value as $fieldValue) {
+                    if (!is_scalar($fieldValue) && $fieldValue !== null) {
+                        $allScalar = false;
+                        break;
+                    }
+                }
+                if ($allScalar) {
+                    $child           = clone $childTemplate;
+                    $child->data     = $value;
+                    $child->rowsOnly = $value === [];
+                }
+                else {
+                    $child = new static($value, $this->getInternalProperties());
+                }
                 $child->position   = $position;
                 $child->isFirst    = $position === 1;
                 $child->isLast     = $position === $count;
@@ -232,6 +260,7 @@ private function setElement(int|string|null $key, mixed $value): void
             else {
                 $this->data[$key] = $value;
             }
+            $this->rowsOnly = false;
             return;
         }
 
@@ -1394,16 +1423,26 @@ private function isNested(): bool
     }
 
     /**
-     * Returns a generator that yields elements, wrapping scalars in SmartString when enabled.
+     * Returns an iterator over the elements, wrapping scalars in SmartString when enabled.
      * Nested SmartArrays are yielded as-is (not wrapped).
      */
     public function getIterator(): Iterator
     {
-        // Return an iterator that yields encoded values for each element
+        // ArrayIterator iterates 1.2-1.3x faster than the wrapping generator below,
+        // and nothing needs wrapping in raw mode or when every value is a row
+        if (!$this->useSmartStrings || $this->rowsOnly) {
+            return new ArrayIterator($this->data);
+        }
+        return $this->wrappingIterator();
+    }
+
+    /**
+     * Yields elements with scalars and nulls wrapped in SmartString (HTML mode only).
+     */
+    private function wrappingIterator(): Iterator
+    {
         foreach ($this->data as $key => $value) {
-            yield $key => $this->useSmartStrings && !$value instanceof self
-                ? new SmartString($value)
-                : $value;
+            yield $key => $value instanceof self ? $value : new SmartString($value);
         }
     }
 

tests/Unit/CreationTest.php

@@ -36,6 +36,39 @@ public function testConstructorWrapsNestedArraysRecursively(string $class): void
         $this->assertInstanceOf($class, $sa->first(), 'child rows take the parent class');
     }
 
+    #[DataProvider('modeProvider')]
+    public function testRowsAreIndependentAndKeepParentMetadata(string $class): void
+    {
+        // All-scalar rows are built from a shared template internally; each row must
+        // still have its own data and the parent's root/mysqli/loadHandler
+        $sa = $class::new([['name' => 'Amy'], ['name' => 'Bob']], ['mysqli' => ['insert_id' => 42]]);
+
+        $first = $sa->first();
+        $last  = $sa->last();
+        $first->name = 'Changed';
+
+        $this->assertModeValue('Bob', $last->name, $class, 'writing one row does not leak into another');
+        $this->assertSame($sa, $first->root());
+        $this->assertSame($sa, $last->root());
+        $this->assertSame(['insert_id' => 42], $last->mysqli());
+        $this->assertSame(1, $first->position());
+        $this->assertTrue($last->isLast());
+    }
+
+    #[DataProvider('modeProvider')]
+    public function testRowContainingNestedArrayConvertsRecursively(string $class): void
+    {
+        // Mixed rows (scalar fields plus a nested array) take the full conversion
+        // path; the nested array still becomes a child of the same class
+        $sa = $class::new([['name' => 'Amy', 'tags' => ['a', 'b']], ['name' => 'Bob', 'tags' => []]]);
+
+        $firstTags = $sa->first()->tags;
+        $this->assertInstanceOf($class, $firstTags);
+        $this->assertSame(['a', 'b'], $firstTags->toArray());
+        $this->assertSame($sa, $firstTags->root(), 'grandchildren still point at the real root');
+        $this->assertSame(2, $sa->last()->position());
+    }
+
     #[DataProvider('modeProvider')]
     public function testNewMatchesConstructor(string $class): void
     {

tests/Unit/DeprecationsTest.php

@@ -753,11 +753,12 @@ public function testSmartArrayRawNewForwardsTheLegacyBooleanToTheConstructorGuar
 
     public function testSmartArrayRawRowsAreAlsoSmartArrayRaw(): void
     {
-        // Every row is built by the deprecated constructor, so a 2-row result
-        // logs three times: the outer array plus one per row
+        // The outer array and the internal row template each run the deprecated
+        // constructor once; cloned rows don't, so the count stays at two
+        // regardless of how many rows the result has
         [$sa, $deprecations] = $this->captureDeprecations(fn() => new SmartArrayRaw([['id' => 1], ['id' => 2]]));
 
-        $this->assertCount(3, $deprecations);
+        $this->assertCount(2, $deprecations);
         $this->assertInstanceOf(SmartArrayRaw::class, $sa->first());
         $this->assertSame(['id' => 1], $sa->first()->toArray());
     }

tests/Unit/IterationTest.php

@@ -89,4 +89,35 @@ public function testEmptyArrayIteratesZeroTimes(string $class): void
     {
         $this->assertSame(0, iterator_count($class::new([])->getIterator()));
     }
+
+    #[DataProvider('modeProvider')]
+    public function testRecordSetYieldsTheStoredRowObjects(string $class): void
+    {
+        // Rows come back by identity, not as copies - metadata like position()
+        // answers the same whether a row came from foreach or first()
+        $sa = $class::new([['id' => 1], ['id' => 2]]);
+
+        $yielded = [];
+        foreach ($sa as $row) {
+            $yielded[] = $row;
+        }
+
+        $this->assertSame($sa->first(), $yielded[0]);
+        $this->assertSame($sa->last(), $yielded[1]);
+    }
+
+    public function testHtmlModeWrapsScalarAddedAfterConstruction(): void
+    {
+        // A record set iterates unwrapped (all rows), but adding a scalar later
+        // must bring back SmartString wrapping for it
+        $sa = SmartArrayHtml::new([['id' => 1]]);
+        $sa->note = '<b>';
+
+        $types = [];
+        foreach ($sa as $key => $value) {
+            $types[$key] = get_debug_type($value);
+        }
+
+        $this->assertSame([0 => SmartArrayHtml::class, 'note' => SmartString::class], $types);
+    }
 }