SmartNull: bracket access signals through $onOffsetAccess like a real row

SmartNull's ArrayAccess methods skipped the deprecation dispatcher, so
bracket calls on missing-data paths (empty result, missing key) were silent
in every mode - a migration sweep with 'throw' missed exactly the call sites
that only run when data is absent. triggerArrayAccessDeprecation() is now a
public static on the Deprecations trait and SmartNull's get/set/unset call
it. offsetExists stays silent, matching the base class, so isset() and ??
don't double-notify. Tests added; SmartNull chaining tests updated to expect
the notices.

Author: daveedis

src/Deprecations.php

@@ -417,7 +417,7 @@ public function chunk(int $size): static
      */
     public function offsetSet(mixed $offset, mixed $value): void
     {
-        $this->triggerArrayAccessDeprecation($offset, 'set');
+        self::triggerArrayAccessDeprecation($offset, 'set');
         $this->setElement($offset, $value);
     }
 
@@ -434,7 +434,7 @@ public function offsetGet(mixed $offset): static|SmartNull|SmartString|string|in
             is_float($offset), is_bool($offset)  => (int) $offset,
             default                              => $offset,
         };
-        $this->triggerArrayAccessDeprecation($offset, 'get');
+        self::triggerArrayAccessDeprecation($offset, 'get');
         return $this->getElement($offset);
     }
 
@@ -459,7 +459,7 @@ public function offsetExists(mixed $offset): bool
      */
     public function offsetUnset(mixed $offset): void
     {
-        $this->triggerArrayAccessDeprecation($offset, 'unset');
+        self::triggerArrayAccessDeprecation($offset, 'unset');
         $this->sourceRows       = null;   // same staleness rule as setElement()
         $this->root->sourceRows = null;
         unset($this->data[$offset]);
@@ -468,9 +468,13 @@ public function offsetUnset(mixed $offset): void
     /**
      * Surface a deprecation notice for array access syntax, dispatched per $onOffsetAccess mode.
      *
+     * Public static so SmartNull, which defines its own ArrayAccess methods, dispatches
+     * through the same rules and modes.
+     *
+     * @internal not part of the supported API
      * @see SmartArrayBase::$onOffsetAccess
      */
-    private function triggerArrayAccessDeprecation(mixed $key, string $operation = 'get'): void
+    public static 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

src/SmartNull.php

@@ -181,9 +181,11 @@ public function count(): int
 
     /**
      * Array reads on a missing value stay missing: returns $this so chains keep working.
+     * Bracket syntax is deprecated everywhere, so it dispatches per $onOffsetAccess first.
      */
     public function offsetGet(mixed $offset): SmartNull
     {
+        SmartArrayBase::triggerArrayAccessDeprecation($offset, 'get');
         return $this;
     }
 
@@ -192,11 +194,13 @@ public function offsetGet(mixed $offset): SmartNull
      */
     public function offsetSet(mixed $offset, mixed $value): void
     {
+        SmartArrayBase::triggerArrayAccessDeprecation($offset, 'set');
         $this->throwCannotSet();
     }
 
     /**
-     * No keys exist on a missing value.
+     * No keys exist on a missing value. Silent like SmartArrayBase::offsetExists,
+     * so isset() and ?? don't signal - the read carries the notice.
      */
     public function offsetExists(mixed $offset): bool
     {
@@ -205,7 +209,8 @@ public function offsetExists(mixed $offset): bool
 
     public function offsetUnset(mixed $offset): void
     {
-        // ArrayAccess requires this; a SmartNull has nothing to unset
+        // Nothing to unset, but the deprecated bracket syntax still signals
+        SmartArrayBase::triggerArrayAccessDeprecation($offset, 'unset');
     }
 
     //endregion

tests/Unit/DeprecationsTest.php

@@ -75,6 +75,7 @@ public function testTraitPublicMethodInventoryIsPinned(): void
             'sprintf',
             'toHtml',
             'toRaw',
+            'triggerArrayAccessDeprecation',   // not an alias: the offset-syntax dispatcher, public so SmartNull can call it
             'withSmartStrings',
         ], $methods);
     }

tests/Unit/GlobalSettingsTest.php

@@ -8,6 +8,7 @@
 use Itools\SmartArray\SmartArray;
 use Itools\SmartArray\SmartArrayBase;
 use Itools\SmartArray\SmartArrayHtml;
+use Itools\SmartArray\SmartNull;
 use Itools\SmartArray\Tests\Support\SmartArrayTestCase;
 use PHPUnit\Framework\Attributes\DataProvider;
 use ReflectionClass;
@@ -497,6 +498,60 @@ public function testNestedReadChainSignalsOncePerLevel(): void
         ], $this->normalizeCaller($deprecations));
     }
 
+    //endregion
+    //region SmartNull (missing keys and empty results)
+
+    #[DataProvider('modeProvider')]
+    public function testSmartNullBracketReadDispatchesLikeARealRow(string $class): void
+    {
+        // Missing-data paths signal too, so a migration sweep also finds the
+        // bracket call sites that only run when a result is empty
+        $smartNull = $class::new([])->first();
+
+        [[$result, $output], $deprecations] = $this->withOffsetAccess('notify', fn() => $this->captureDeprecations(
+            fn() => $this->captureOutput(fn() => $smartNull['name'])
+        ));
+
+        $this->assertInstanceOf(SmartNull::class, $result, 'the read still chains');
+        $this->assertSame($this->expectedEcho(["Replace ['name'] with ->name"]), $this->normalizeCaller($output));
+        $this->assertSame($this->expectedMessages(["Replace ['name'] with ->name"]), $this->normalizeCaller($deprecations));
+    }
+
+    #[DataProvider('modeProvider')]
+    public function testSmartNullBracketAccessThrowsInThrowMode(string $class): void
+    {
+        $smartNull = $class::new([])->first();
+
+        $read = $this->withOffsetAccess('throw', fn() => $this->catchThrowable(fn() => $smartNull['name']));
+        $this->assertInstanceOf(RuntimeException::class, $read);
+        $this->assertSame("Replace ['name'] with ->name in FILE:LINE.", $this->normalizeCaller($read->getMessage()));
+
+        $write = $this->withOffsetAccess('throw', fn() => $this->catchThrowable(fn() => $smartNull['name'] = 'x'));
+        $this->assertInstanceOf(RuntimeException::class, $write);
+        $this->assertSame("Replace ['name'] with ->name = \$value in FILE:LINE.", $this->normalizeCaller($write->getMessage()));
+
+        $unset = $this->withOffsetAccess('throw', fn() => $this->catchThrowable(function () use ($smartNull) {
+            unset($smartNull['name']);
+        }));
+        $this->assertInstanceOf(RuntimeException::class, $unset);
+    }
+
+    #[DataProvider('modeProvider')]
+    public function testSmartNullExistenceChecksStaySilent(string $class): void
+    {
+        // offsetExists stays silent like SmartArrayBase's, so isset() and ??
+        // don't signal on missing-data paths either - even in throw mode
+        $smartNull = $class::new([])->first();
+
+        [[$results, $output], $deprecations] = $this->withOffsetAccess('throw', fn() => $this->captureDeprecations(
+            fn() => $this->captureOutput(fn() => [isset($smartNull['name']), $smartNull['name'] ?? 'default'])
+        ));
+
+        $this->assertSame([false, 'default'], $results);
+        $this->assertSame('', $output);
+        $this->assertSame([], $deprecations);
+    }
+
     //endregion
     //region Helpers
 

tests/Unit/SmartNullTest.php

@@ -146,8 +146,8 @@ public function testArrayAccessChainingReturnsTheSameSmartNull(string $class): v
 
         [$result, $output] = $this->captureOutput(fn() => $smartNull['a']['b'][0]);
 
-        $this->assertSame($smartNull, $result, 'array reads on SmartNull are exempt from the offset-access deprecation');
-        $this->assertSame('', $output);
+        $this->assertSame($smartNull, $result, 'array reads return $this, so chains keep working');
+        $this->assertSame(3, substr_count($output, "\nDeprecated: "), 'bracket syntax notifies on missing-data paths like anywhere else');
     }
 
     #[DataProvider('modeProvider')]
@@ -158,7 +158,7 @@ public function testMixedPropertyArrayAndMethodChainResolvesToNull(string $class
         [$result, $output] = $this->captureOutput(fn() => $smartNull['rows']->first()->name->value());
 
         $this->assertNull($result, 'the whole chain resolves to null with no fatal');
-        $this->assertSame('', $output);
+        $this->assertSame(1, substr_count($output, "\nDeprecated: "), 'the one bracket read notifies');
     }
 
     #[DataProvider('modeProvider')]