get, nth: restore per-mode return types on the subclasses

Moving get() and nth() into the Deprecations trait dropped the narrowing
overrides v2.7 had, so static analysis saw the wide base union at every call
site: raw-mode get() claimed it could return SmartString, HTML-mode get()
claimed raw scalars. Both subclasses now redeclare them next to the other
narrowed proxies, with the deprecation markers repeated so IDEs keep flagging
them. get()'s proxy forwards func_get_args() because get() branches on
whether a default was passed - a fixed second argument would repeat the 2.7
where() inversion.

Author: daveedis

src/SmartArray.php

@@ -6,6 +6,7 @@
 
 use InvalidArgumentException;
 use Itools\SmartString\SmartString;
+use JetBrains\PhpStorm\Deprecated;
 
 /**
  * SmartArray - Collection returning raw PHP values (string, int, float, bool, null).
@@ -236,13 +237,35 @@ public function load(string $field): static|SmartNull
     }
 
     //endregion
-    //region Deprecated Array Access
+    //region Deprecated Access
 
     /** {@inheritDoc} */
     public function offsetGet(mixed $offset): static|SmartNull|string|int|float|bool|null
     {
         return parent::offsetGet($offset);
     }
 
+    /**
+     * {@inheritDoc}
+     * @deprecated Use property access: ->key, or ->{'users.id'} for keys property syntax
+     *             can't type. For a missing-key default use ->key ?? $default.
+     */
+    #[Deprecated(reason: "use property access ->key or ->{'key'}, with ?? for defaults")]
+    public function get(int|string|SmartString|SmartNull $key, mixed $default = null): static|SmartNull|string|int|float|bool|null
+    {
+        // func_get_args: get() branches on whether $default was passed, so forward the real arg count
+        return parent::get(...func_get_args());
+    }
+
+    /**
+     * {@inheritDoc}
+     * @deprecated Use ->at() - same behavior, new name
+     */
+    #[Deprecated(reason: 'renamed to at()', replacement: '%class%->at()')]
+    public function nth(int $index): static|SmartNull|string|int|float|bool|null
+    {
+        return parent::nth($index);
+    }
+
     //endregion
 }

src/SmartArrayHtml.php

@@ -5,6 +5,7 @@
 use InvalidArgumentException;
 use Iterator;
 use Itools\SmartString\SmartString;
+use JetBrains\PhpStorm\Deprecated;
 
 /**
  * SmartArrayHtml - Collection returning SmartString values for HTML safety.
@@ -231,13 +232,35 @@ public function load(string $field): static|SmartNull
     }
 
     //endregion
-    //region Deprecated Array Access
+    //region Deprecated Access
 
     /** {@inheritDoc} */
     public function offsetGet(mixed $offset): static|SmartNull|SmartString
     {
         return parent::offsetGet($offset);
     }
 
+    /**
+     * {@inheritDoc}
+     * @deprecated Use property access: ->key, or ->{'users.id'} for keys property syntax
+     *             can't type. For a missing-key default use ->key ?? $default.
+     */
+    #[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
+    {
+        // func_get_args: get() branches on whether $default was passed, so forward the real arg count
+        return parent::get(...func_get_args());
+    }
+
+    /**
+     * {@inheritDoc}
+     * @deprecated Use ->at() - same behavior, new name
+     */
+    #[Deprecated(reason: 'renamed to at()', replacement: '%class%->at()')]
+    public function nth(int $index): static|SmartNull|SmartString
+    {
+        return parent::nth($index);
+    }
+
     //endregion
 }