deprecations: silently deprecate get() and set(), teach property access everywhere

- get() and set() move to the Silent Aliases region of DeprecatedAliases:
  same behavior, IDE strikethrough, no runtime signal. get('') and
  set('', $value) stay the only way to reach an empty-string key, so the
  ''-key suggestions still name them.
- Docs and deprecation notices now point at property access only: ->key,
  ->key = $value, ->{'users.id'} for keys property syntax can't type, and
  ?? for missing-key defaults. Write-side [] notices suggest assignment
  instead of ->set().
- README, help.txt, and UPGRADING drop get()/set(); the indexBy example
  uses brace syntax.
- Tests: get()/set() behavior stays pinned in ReadAccessTest and
  WriteAccessTest, the alias inventory and no-signal checks cover them in
  DeprecationsTest, and incidental get()/set()/nth() calls in other tests
  switch to property access and at().

Author: daveedis

CHANGELOG.md

@@ -11,7 +11,7 @@
 - `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.
+- `at($index)` - new name for `nth()`: get an element by position, zero-based, negative indices count from the end. Matches JavaScript's `Array.at()`. `$row->key` 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.
 
 ### Changed
@@ -29,7 +29,7 @@
 - `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.
+- 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()`.
 - `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.
@@ -43,6 +43,8 @@
 - `pluck($valueField, $keyField)` - use `column()` instead, same arguments and behavior: `->column('name')`, `->column('name', 'id')`. One name per behavior, and `column()` matches PHP's `array_column()`. Still works with no runtime notice - IDEs show a strikethrough with the replacement; removed from README and help().
 - `each($callback)` - use a `foreach` loop instead, same behavior in plain PHP. Still works with no runtime notice - IDEs show a strikethrough with the replacement; removed from help(). It had no measured uses and a foreach is clearer and faster.
 - `sprintf($format)` - use `map()` with an inline format string instead: `$list->map(fn($v) => "<li>$v</li>")`. On SmartArrayHtml, encode explicitly and convert to raw mode first so the finished HTML isn't re-encoded on output: `$row->asRaw()->map(fn($v) => "<td>" . htmlspecialchars((string)$v) . "</td>")->implode("\n")`. The method still works unchanged with no runtime notice - IDEs show a strikethrough with the replacement; removed from README and help(). It was a second formatting syntax that only saw use inside CMS Builder.
+- `get($key, $default)` - use property access instead: `$row->name`, `$row->{'users.id'}` for keys property syntax can't type, and `$row->name ?? 'n/a'` for missing-key defaults. Still works unchanged with no runtime notice, including the default parameter - IDEs show a strikethrough with the replacement; removed from README and help(). It was a second documented way to read every element; the docs now teach one form, and property access is 1.1-1.6x faster. `get('')` remains the only way to read an empty-string key - the brace form is a fatal error.
+- `set($key, $value)` - use property assignment instead: `$row->name = $value`, or `$row->{'users.id'} = $value` for keys property syntax can't type. Still works unchanged with no runtime notice - IDEs show a strikethrough with the replacement; removed from README and help(). Deprecated together with `get()` - one form for reads, one for writes. `set('', $value)` remains the only way to write an empty-string key.
 
 ### Removed
 - `usingSmartStrings()` - use `instanceof SmartArrayHtml` to check the mode; the class is the mode. The method was never documented and had no found uses.

README.md

@@ -179,9 +179,9 @@ $authors = [
 // Create a lookup array indexed by author_id
 $authorById = SmartArray::new($authors)->indexBy('author_id')->asHtml();
 
-// Now you can quickly look up authors by their ID
-echo $authorById->get(101)->name;  // Output: Jane Austen
-echo $authorById->get(103)->genre; // Output: Science Fiction
+// Now you can quickly look up authors by their ID (braces for numeric keys)
+echo $authorById->{101}->name;  // Output: Jane Austen
+echo $authorById->{103}->genre; // Output: Science Fiction
 
 // Particularly useful when joining data from multiple sources
 $articles = [
@@ -192,7 +192,7 @@ $articles = [
 
 // Display articles with author information
 foreach (SmartArray::new($articles)->asHtml() as $article) {
-    $author = $authorById->get($article->author_id);
+    $author = $authorById->{$article->author_id};
     echo "Title: $article->title\n";
     echo "By: $author->name ($author->genre)\n\n";
 }
@@ -463,9 +463,9 @@ Note: All methods return a new `SmartArray` object unless otherwise specified.
 |                       |                 $array->asRaw() | Return values as raw PHP types (lazy conversion - returns same object if already using raw values)                           |
 |                       |     SmartArrayHtml::new($array) | Create a SmartArray with HTML-safe SmartString values directly (equivalent to SmartArray::new()->asHtml())                   |
 | Value Access          |                       $obj->key | Get a value using property syntax                                                                                            |
-|                       |                        get(key) | Get a value by key (for numeric keys or keys with special characters)                                                        |
-|                       |               get(key, default) | Get a value with optional default if key not found                                                                           |
-|                       |                 set(key, value) | Set a value by key (for numeric keys or keys with special characters)                                                        |
+|                       |              $obj->{'users.id'} | Get keys property syntax can't type (dots, dashes, numeric keys)                                                             |
+|                       |              $obj->key = $value | Set a value using property syntax                                                                                            |
+|                       |          $obj->key ?? 'default' | Fallback for possibly-missing keys, same as plain PHP                                                                        |
 |                       |                         first() | Get the first element                                                                                                        |
 |                       |                          last() | Get the last element                                                                                                         |
 |                       |                       at(index) | Get element by position, ignoring keys (0=first, -1=last)                                                                    |

UPGRADING.md

@@ -197,13 +197,13 @@ Full lists of what changed per release: [CHANGELOG.md](CHANGELOG.md).
 > ```php
 > echo $row['name'];         // works, but prints a Deprecated: notice into the page
 > echo $row->name;           // correct
-> echo $row->get('name');    // correct - for keys property syntax can't type, like 'users.id'
+> echo $row->{'users.id'};   // correct - for keys property syntax can't type
 > ```
 >
 > Fix:
 >
 > - Follow the file and line in each notice and switch to `->key` or
->   `->get('key')`
+>   `->{'key'}`
 > - Sites mid-migration can silence the echo (notices still reach error
 >   logs): `SmartArrayBase::$onOffsetAccess = 'log';`
 

src/DeprecatedAliases.php

@@ -47,8 +47,9 @@ trait DeprecatedAliases
     /**
      * Controls how deprecated `$array['key']` offset access is surfaced.
      *
-     * Offset access (`[]` syntax) is deprecated in favor of property access
-     * (`$array->key`) or the explicit `->get()` / `->set()` methods. This setting
+     * Offset access (`[]` syntax) is deprecated in favor of property access:
+     * `$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.
@@ -178,6 +179,92 @@ public function sprintf(string $format): SmartArray
         return new SmartArray($newArray, $properties);
     }
 
+    /**
+     * Returns the element at $key, same as $array->key, with an optional
+     * default for missing keys.
+     *
+     * The default replaces missing keys only, never stored nulls. Smart keys
+     * and defaults unwrap first; defaults then wrap for this array's mode the
+     * same as a stored value would (arrays become same-mode SmartArrays).
+     *
+     * get('') is the only way to read an empty-string key: ->{''} is a PHP
+     * fatal error.
+     *
+     * @deprecated Use property access: ->key, or ->{'users.id'} for keys property syntax
+     *             can't type. For a missing-key default use ->key ?? $default.
+     *
+     * @param int|string|SmartString|SmartNull $key The key to retrieve; Smart values unwrap first
+     * @param mixed $default Returned when $key doesn't exist; treated like a stored value
+     * @return static|SmartNull|SmartString|string|int|float|bool|null
+     */
+    #[Deprecated(reason: "use property access ->key or ->{'key'}, with ?? for defaults")]
+    public function get(int|string|SmartString|SmartNull $key, mixed $default = null): static|SmartNull|SmartString|string|int|float|bool|null
+    {
+        // Unwrap Smart keys, then coerce like PHP array keys: null reads key '', bool/float truncate to int
+        if ($key instanceof SmartString || $key instanceof SmartNull) {
+            $key = $key->value();
+            $key = match (true) {
+                is_int($key), is_string($key) => $key,
+                is_null($key)                 => '',
+                default                       => (int) $key,
+            };
+        }
+
+        // return default if key not found
+        if (func_num_args() >= 2 && !array_key_exists($key, $this->data)) {
+            // Defaults act like stored values: Smart defaults (SmartString,
+            // SmartArray, SmartNull) unwrap to raw equivalents, then everything
+            // wraps for this array's mode the same as a stored value would
+            if ($default instanceof SmartBase || $default instanceof SmartString) {
+                $default = self::getRawValue($default);
+            }
+            return match (true) {
+                is_scalar($default), is_null($default) => $this->useSmartStrings ? new SmartString($default) : $default,
+                is_array($default)                     => new static($default, $this->getInternalProperties()),
+                default                                => throw new CallerException("Unsupported default value type: " . get_debug_type($default)),
+            };
+        }
+
+        // skip if empty
+        if (empty($this->data)) {
+            return $this->newSmartNull();
+        }
+
+        // Return via getElement (no deprecation warning - Silent stage)
+        if (array_key_exists($key, $this->data)) {
+            return $this->getElement($key);
+        }
+
+        // Show warning if key doesn't exist (only when no default provided)
+        $this->warnIfMissing($key, 'offset');
+
+        return $this->newSmartNull();
+    }
+
+    /**
+     * Sets a value by key, same as $array->key = $value. Returns $this for
+     * chaining.
+     *
+     * Smart values are unwrapped on storage: a SmartString stores its raw
+     * value, a SmartArray stores as a child array of this array's mode, and
+     * a SmartNull stores as null.
+     *
+     * set('') is the only way to write an empty-string key: ->{''} = $value
+     * is a PHP fatal error.
+     *
+     * @deprecated Use property assignment: ->key = $value, or ->{'users.id'} = $value for keys property syntax can't type
+     *
+     * @param int|string $key The key to set
+     * @param mixed $value The value to set
+     * @return static Returns $this for method chaining
+     */
+    #[Deprecated(reason: "use property assignment ->key = \$value or ->{'key'} = \$value")]
+    public function set(int|string $key, mixed $value): static
+    {
+        $this->setElement($key, $value);
+        return $this;
+    }
+
     //endregion
     //region Logged Aliases
 
@@ -300,7 +387,7 @@ public function chunk(int $size): static
     /**
      * Sets a value in the SmartArray using array syntax.
      *
-     * @deprecated Use ->set('key', $value) or ->key = $value instead of $array['key'] = $value
+     * @deprecated Use ->key = $value or ->{'key'} = $value instead of $array['key'] = $value
      *
      * Note: If you add a key after the array is created the position properties will not be updated.
      * If needed you can recreate the array like this: $newArray = SmartArray::new($oldArray->toArray());
@@ -319,7 +406,7 @@ public function offsetSet(mixed $offset, mixed $value): void
     /**
      * Retrieves a value from the SmartArray using array syntax.
      *
-     * @deprecated Use ->property or ->get('key') instead of $array['key']
+     * @deprecated Use ->property or ->{'key'} instead of $array['key']
      */
     public function offsetGet(mixed $offset): static|SmartNull|SmartString|string|int|float|bool|null
     {
@@ -371,10 +458,11 @@ private function triggerArrayAccessDeprecation(mixed $key, string $operation = '
         // 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)",
+                is_null($key)    => 'an explicit key: ->key = $value',
+                is_int($key)     => '->{' . $key . '} = $value',
                 $isValidPropName => "->$key = \$value",
-                default          => "->set('$key', \$value) or ->{'$key'} = \$value",
+                $key === ''      => "->set('', \$value)", // ->{''} = $value is a fatal "Cannot access empty property"
+                default          => "->{'$key'} = \$value",
             },
             default => match (true) {
                 is_int($key)                 => '->{' . $key . '}',

src/SmartArray.php

@@ -107,17 +107,6 @@ public function asHtml(): SmartArrayHtml
     //endregion
     //region Value Access
 
-    /** {@inheritDoc} */
-    public function get(int|string|SmartString|SmartNull $key, mixed $default = null): static|SmartNull|string|int|float|bool|null
-    {
-        // Must use func_num_args() check here and call parent appropriately,
-        // because parent uses func_num_args() to detect if default was provided
-        if (func_num_args() >= 2) {
-            return parent::get($key, $default);
-        }
-        return parent::get($key);
-    }
-
     /** {@inheritDoc} */
     public function first(): static|SmartNull|string|int|float|bool|null
     {