deprecations: keep offsetExists() silent so ?? and empty() notify once

PHP calls offsetExists() then offsetGet() for $arr['key'] ?? and empty($arr['key']), so the notice added to existence checks this release printed every message twice for those forms. offsetExists() is signal-free again, matching 2.7.0: the read carries the one notice, and a bare isset() with no read stays silent but still returns the right answer. Dropped the CHANGELOG bullet announcing notices on existence checks and updated the test matrix to pin the new contract.

Author: daveedis

CHANGELOG.md

@@ -121,11 +121,6 @@ the docs - IDEs show a strikethrough with the replacement.
   `$row->missing->or('n/a')` on a raw array throws the standard
   undefined-method Error instead of returning an HTML-encoding SmartString.
   Raw fallbacks use `??`. HTML mode is unchanged.
-- `isset($array['key'])` and `empty($array['key'])` 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. Property-syntax checks (`isset($array->key)`) stay
-  signal-free.
 - `set()`, `->key = $value`, and array assignment unwrap Smart values
   (SmartString, SmartArray, SmartNull) instead of throwing, so values copy
   between arrays in any mode without calling `->value()` first. SmartNull
@@ -168,10 +163,8 @@ the docs - IDEs show a strikethrough with the replacement.
   TypeError that named library internals. `unset()` and `isset()` already
   worked this way.
 - 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.
+  writes, and `unset()`: `->key` and `->key = $value` for property-safe
+  names, `->{0}` for integer keys, `->{'users.id'}` for other keys.
   Null and `''` keys suggest `->get('')` / `->set('', $value)` - the brace
   form is a fatal error for an empty property name.
 - Unknown methods on `SmartNull` throw the same `Error` as the rest of the

src/Deprecations.php

@@ -51,8 +51,10 @@ trait Deprecations
      * `$array->key` for reads, `$array->key = $value` for writes, and brace
      * syntax (`$array->{'users.id'}`) for keys property syntax can't type. This setting
      * controls how the library signals that deprecation at runtime. It covers
-     * reads, writes, unset(), and isset()/empty() checks alike; only the
-     * property forms (`$array->key`, `isset($array->key)`) are signal-free.
+     * reads, writes, and unset(); existence checks (offsetExists) are signal-free
+     * because PHP also calls offsetGet() for `??` and empty(), which carries the
+     * one notice. Property forms (`$array->key`, `isset($array->key)`) are always
+     * signal-free.
      *
      *     'log'    - trigger_error(E_USER_DEPRECATED) only. Silent unless surfaced
      *                by PHP's error handling. Use for legacy codebases mid-migration.
@@ -438,7 +440,9 @@ public function offsetGet(mixed $offset): static|SmartNull|SmartString|string|in
      */
     public function offsetExists(mixed $offset): bool
     {
-        $this->triggerArrayAccessDeprecation($offset, 'exists');
+        // No notice here: PHP calls offsetExists() then offsetGet() for `??` and empty(),
+        // and offsetGet() already notifies, so one here would print every message twice.
+        // A bare isset() with no read stays silent; any access that reads data notifies.
         return isset($this->data[$offset]);
     }
 

tests/Unit/GlobalSettingsTest.php

@@ -20,8 +20,9 @@
  * Covers the full matrix: modes (notify/log/throw) x operations (offsetGet,
  * offsetSet, append, offsetUnset, offsetExists via isset() and empty()), the
  * exact suggestion text for each key shape, and the invalid-mode error. Also
- * pins what must stay signal-free: property syntax and the library's own
- * internal element access.
+ * pins what must stay signal-free: property syntax, existence checks
+ * (offsetExists - the read carries the notice for `??` and empty()), and the
+ * library's own internal element access.
  *
  * Every test swaps the static through withOffsetAccess(), which restores it in a
  * finally block so a failure here cannot poison other test files.
@@ -68,18 +69,19 @@ private static function offsetOperations(): array
             'unset int key'           => [function (SmartArrayBase $sa) { unset($sa[0]); },          ["Replace [0] with ->{0}"]],
             'unset invalid prop name' => [function (SmartArrayBase $sa) { unset($sa['users.id']); }, ["Replace ['users.id'] with ->{'users.id'}"]],
 
-            // offsetExists via isset(): one call, whether or not the key is there
-            'isset string key'        => [fn(SmartArrayBase $sa) => isset($sa['name']),     ["Replace ['name'] with ->name"]],
-            'isset int key'           => [fn(SmartArrayBase $sa) => isset($sa[0]),          ["Replace [0] with ->{0}"]],
-            'isset invalid prop name' => [fn(SmartArrayBase $sa) => isset($sa['users.id']), ["Replace ['users.id'] with ->{'users.id'}"]],
-            'isset missing key'       => [fn(SmartArrayBase $sa) => isset($sa['zzz']),      ["Replace ['zzz'] with ->zzz"]],
-
-            // offsetExists via empty(): PHP calls offsetExists, then offsetGet when the key exists,
-            // so an existing key signals twice for one empty() check - both notices give the
-            // same suggestion (reads and existence checks share one suggestion style)
-            'empty existing key'      => [fn(SmartArrayBase $sa) => empty($sa['name']), ["Replace ['name'] with ->name", "Replace ['name'] with ->name"]],
-            'empty int key'           => [fn(SmartArrayBase $sa) => empty($sa[0]),      ["Replace [0] with ->{0}", "Replace [0] with ->{0}"]],
-            'empty missing key'       => [fn(SmartArrayBase $sa) => empty($sa['zzz']),  ["Replace ['zzz'] with ->zzz"]],
+            // offsetExists via isset(): silent - PHP also calls offsetGet() for `??` and
+            // empty(), which carries the one notice, so a notice here would double every
+            // message. A bare isset() gives no signal but still returns the right answer.
+            'isset string key'        => [fn(SmartArrayBase $sa) => isset($sa['name']),     []],
+            'isset int key'           => [fn(SmartArrayBase $sa) => isset($sa[0]),          []],
+            'isset invalid prop name' => [fn(SmartArrayBase $sa) => isset($sa['users.id']), []],
+            'isset missing key'       => [fn(SmartArrayBase $sa) => isset($sa['zzz']),      []],
+
+            // offsetExists via empty(): offsetExists is silent, then PHP calls offsetGet
+            // when the key exists - one notice for existing keys, none for missing ones
+            'empty existing key'      => [fn(SmartArrayBase $sa) => empty($sa['name']), ["Replace ['name'] with ->name"]],
+            'empty int key'           => [fn(SmartArrayBase $sa) => empty($sa[0]),      ["Replace [0] with ->{0}"]],
+            'empty missing key'       => [fn(SmartArrayBase $sa) => empty($sa['zzz']),  []],
         ];
     }
 
@@ -140,7 +142,7 @@ public function testNotifyPerformsTheOperation(string $class): void
         $this->assertTrue($issetName);
         $this->assertFalse($issetMissing);
         $this->assertSame(['name' => 'Bob', '' => 'blank', 0 => 'zero', 'city' => 'Vancouver', 1 => 'appended'], $sa->toArray());
-        $this->assertSame(6, substr_count($output, "\nDeprecated: "), 'one notice per offset operation');
+        $this->assertSame(4, substr_count($output, "\nDeprecated: "), 'one notice per read/write; isset checks are silent');
     }
 
     //endregion
@@ -190,8 +192,12 @@ public function testThrowRaisesRuntimeExceptionWithTheSuggestion(string $class,
             fn() => $this->captureOutput(fn() => $this->catchThrowable(fn() => $operation($sa)))
         ));
 
-        $this->assertInstanceOf(RuntimeException::class, $thrown);
-        $this->assertSame($expectedMessages[0] . ' in FILE:LINE.', $this->normalizeCaller($thrown->getMessage()));
+        if ($expectedMessages === []) {
+            $this->assertNull($thrown, 'signal-free operations run normally in throw mode');
+        } else {
+            $this->assertInstanceOf(RuntimeException::class, $thrown);
+            $this->assertSame($expectedMessages[0] . ' in FILE:LINE.', $this->normalizeCaller($thrown->getMessage()));
+        }
         $this->assertSame('', $output, 'throw mode replaces the notice, it does not add to it');
         $this->assertSame([], $deprecations, 'throw mode exits before trigger_error()');
     }
@@ -287,7 +293,7 @@ public function testInvalidModeThrowsForEveryOffsetOperation(): void
                 'set'    => function () use ($sa) { $sa['city'] = 'Vancouver'; },
                 'append' => function () use ($sa) { $sa[] = 'appended'; },
                 'unset'  => function () use ($sa) { unset($sa['name']); },
-                'isset'  => fn() => isset($sa['name']),
+                // no 'isset' row: offsetExists is signal-free and never consults the setting
             ];
 
             foreach ($operations as $label => $operation) {
@@ -431,36 +437,34 @@ public function testNullOffsetExistsAndUnsetUseTheEmptyStringKey(): void
 
         $this->assertTrue($exists);
         $this->assertSame([], $sa->toArray());
+
+        // One notice, from the unset - the isset is signal-free
         $this->assertSame(
-            "\nDeprecated: Replace [] with ->get('') in FILE:LINE.\n\nDeprecated: Replace [] with ->get('') in FILE:LINE.\n",
+            "\nDeprecated: Replace [] with ->get('') in FILE:LINE.\n",
             $this->normalizeCaller($output),
         );
         $this->assertSame(
-            ["Replace [] with ->get('') in FILE:LINE.", "Replace [] with ->get('') in FILE:LINE."],
+            ["Replace [] with ->get('') in FILE:LINE."],
             $this->normalizeCaller($deprecations),
         );
     }
 
     //endregion
     //region Nested chains
 
-    public function testNestedIssetChainSignalsThreeTimes(): void
+    public function testNestedIssetChainSignalsOnce(): void
     {
-        // isset($sa['user']['name']) reports ['user'] twice - PHP checks the outer key
-        // with offsetExists, then reads it with offsetGet to reach the inner one. That
-        // call sequence is PHP's, not ours; all notices agree on the suggestion.
+        // isset($sa['user']['name']): PHP checks the outer key with offsetExists
+        // (silent), reads it with offsetGet (the one notice) to reach the inner
+        // offsetExists (silent). That call sequence is PHP's, not ours.
         $sa = SmartArray::new(['user' => ['name' => 'Bob']]);
 
         [$exists, $deprecations] = $this->withOffsetAccess('log', fn() => $this->captureDeprecations(
             fn() => isset($sa['user']['name'])
         ));
 
         $this->assertTrue($exists);
-        $this->assertSame([
-            "Replace ['user'] with ->user in FILE:LINE.",
-            "Replace ['user'] with ->user in FILE:LINE.",
-            "Replace ['name'] with ->name in FILE:LINE.",
-        ], $this->normalizeCaller($deprecations));
+        $this->assertSame(["Replace ['user'] with ->user in FILE:LINE."], $this->normalizeCaller($deprecations));
     }
 
     public function testNestedReadChainSignalsOncePerLevel(): void

tests/Unit/ReadAccessTest.php

@@ -371,16 +371,14 @@ public function testIssetTreatsStoredNullAsMissing(string $class): void
         $this->assertFalse(isset($sa->middle));
         $this->assertFalse(isset($sa->zzz));
 
-        // Array-syntax existence checks follow $onOffsetAccess like reads and
-        // writes do (default 'notify'); only the property forms are signal-free
+        // Array-syntax existence checks are signal-free: for `??` and empty()
+        // PHP also calls offsetGet(), which carries the one notice
         [, $output] = $this->captureOutput(function () use ($sa) {
             $this->assertFalse($sa->offsetExists('middle'));
             $this->assertFalse($sa->offsetExists('zzz'));
             $this->assertTrue(isset($sa['name']));
         });
-        $this->assertSame(3, substr_count($output, 'Deprecated:'), 'one notice per array-syntax check');
-        $this->assertStringContainsString("Replace ['middle'] with ->middle", $output);
-        $this->assertStringContainsString("Replace ['zzz'] with ->zzz", $output);
+        $this->assertSame('', $output, 'existence checks emit nothing');
     }
 
     #[DataProvider('modeProvider')]