messages: recommend ::new() everywhere, document why it exists

Constructor errors said "use new SmartArrayHtml($data)" but the docs
teach SmartArrayHtml::new(). Standardized every message on ::new(),
and the docblocks now say it exists for chaining on pre-8.4 PHP.

Also switched strings with escaped \$ to single quotes where nothing
needed interpolating.

Author: daveedis

src/DeprecatedAliases.php

@@ -244,7 +244,7 @@ private function triggerArrayAccessDeprecation(mixed $key, string $operation = '
         // 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_null($key)    => '->set($key, $value) using an explicit key',
                 is_int($key)     => "->set($key, \$value)",
                 $isValidPropName => "->$key = \$value",
                 default          => "->set('$key', \$value) or ->{'$key'} = \$value",

src/SmartArray.php

@@ -44,18 +44,18 @@ public function __construct(array $array = [], bool|array|null $properties = [])
         // Handle deprecated boolean parameter: true contradicts this class (throw),
         // false is redundant (deprecation only)
         if ($properties === true) {
-            self::logDeprecation("new SmartArray(\$data, true) is deprecated. Use new SmartArrayHtml(\$data) instead.");
-            throw new InvalidArgumentException("Cannot create SmartArray with useSmartStrings=true. Use new SmartArrayHtml(\$data) instead.");
+            self::logDeprecation('Creating a SmartArray with useSmartStrings=true is deprecated. Use SmartArrayHtml::new($data) instead.');
+            throw new InvalidArgumentException('Cannot create SmartArray with useSmartStrings=true. Use SmartArrayHtml::new($data) instead.');
         }
         if ($properties === false) {
-            self::logDeprecation("Passing false to SmartArray is deprecated. Just use SmartArray(\$data)");
+            self::logDeprecation('Passing false to SmartArray is deprecated. Just use SmartArray::new($data)');
             $properties = [];
         }
 
         // Handle deprecated useSmartStrings in array
         if (is_array($properties) && ($properties['useSmartStrings'] ?? false) === true) {
-            self::logDeprecation("new SmartArray(\$data, ['useSmartStrings' => true]) is deprecated. Use new SmartArrayHtml(\$data) instead.");
-            throw new InvalidArgumentException("Cannot create SmartArray with useSmartStrings=true. Use new SmartArrayHtml(\$data) instead.");
+            self::logDeprecation('Creating a SmartArray with useSmartStrings=true is deprecated. Use SmartArrayHtml::new($data) instead.');
+            throw new InvalidArgumentException('Cannot create SmartArray with useSmartStrings=true. Use SmartArrayHtml::new($data) instead.');
         }
 
         // Force useSmartStrings to false for raw values
@@ -68,6 +68,12 @@ public function __construct(array $array = [], bool|array|null $properties = [])
     /**
      * Create a new SmartArray that returns raw values without SmartString wrapping.
      *
+     * Same as `new SmartArray()`, but chainable on every supported PHP version:
+     * before PHP 8.4, `new SmartArray($data)->pluck('id')` is a syntax error without
+     * wrapping parentheses; `SmartArray::new($data)->pluck('id')` works everywhere.
+     *
+     *     $users = SmartArray::new($records)->indexBy('user_id');
+     *
      * @param array $array The input array to convert
      * @param array|bool $properties Optional properties to pass to the constructor (legacy boolean handled by the constructor)
      * @return static A new SmartArray instance

src/SmartArrayBase.php

@@ -1238,7 +1238,7 @@ public function __debugInfo(): array
         $output = [];
         if ($this === $this->root()) {
             // Call ->help() for usage examples and documentation, or ->debug() to view metadata
-            $output["README:" . self::stripNamespace(static::class) . ":private"] = "Call \$obj->help() for documentation, or ->debug() to view metadata";
+            $output["README:" . self::stripNamespace(static::class) . ":private"] = 'Call $obj->help() for documentation, or ->debug() to view metadata';
             $output["*useSmartStrings*:private"] = match ($this->useSmartStrings) {
                 true  => "true, // Values are returned as SmartString objects on access\n",
                 false => "false, // Values are returned **as-is** on access (no extra encoding)\n",
@@ -1504,7 +1504,7 @@ public function __toString(): string
         // PHP Error: Fatal error: Uncaught Error: Object of class Itools\SmartArray\SmartArray could not be converted to string in C:\path\file.php:27
         $warning = "Can't convert SmartArray to string $inFileOnLine.\n\n";
         $warning .= "In double-quoted strings, use \"\$var->property\" for properties, but wrap methods in braces like \"{\$var->method()}\"\n\n";
-        $warning .= "For more info: \$var->help()";
+        $warning .= 'For more info: $var->help()';
 
         // output warning
         echo "\nWarning: $warning\n\n";           // Output with echo so PHP doesn't add the filename and line number of this function on the end

src/SmartArrayHtml.php

@@ -40,18 +40,18 @@ public function __construct(array $array = [], bool|array|null $properties = [])
         // Handle deprecated boolean parameter: false contradicts this class (throw),
         // true is redundant (deprecation only)
         if ($properties === false) {
-            self::logDeprecation("new SmartArrayHtml(\$data, false) is deprecated. Use new SmartArray(\$data) instead.");
-            throw new InvalidArgumentException("Cannot create SmartArrayHtml with useSmartStrings=false. Use new SmartArray(\$data) instead.");
+            self::logDeprecation('Creating a SmartArrayHtml with useSmartStrings=false is deprecated. Use SmartArray::new($data) instead.');
+            throw new InvalidArgumentException('Cannot create SmartArrayHtml with useSmartStrings=false. Use SmartArray::new($data) instead.');
         }
         if ($properties === true) {
-            self::logDeprecation("Passing true to SmartArrayHtml is deprecated. Just use SmartArrayHtml(\$data)");
+            self::logDeprecation('Passing true to SmartArrayHtml is deprecated. Just use SmartArrayHtml::new($data)');
             $properties = [];
         }
 
         // Handle deprecated useSmartStrings in array
         if (is_array($properties) && ($properties['useSmartStrings'] ?? true) === false) {
-            self::logDeprecation("new SmartArrayHtml(\$data, ['useSmartStrings' => false]) is deprecated. Use new SmartArray(\$data) instead.");
-            throw new InvalidArgumentException("Cannot create SmartArrayHtml with useSmartStrings=false. Use new SmartArray(\$data) instead.");
+            self::logDeprecation('Creating a SmartArrayHtml with useSmartStrings=false is deprecated. Use SmartArray::new($data) instead.');
+            throw new InvalidArgumentException('Cannot create SmartArrayHtml with useSmartStrings=false. Use SmartArray::new($data) instead.');
         }
 
         // Force useSmartStrings to true so values are SmartStrings
@@ -64,6 +64,12 @@ public function __construct(array $array = [], bool|array|null $properties = [])
     /**
      * Create a new SmartArrayHtml that returns SmartString objects for HTML safety.
      *
+     * Same as `new SmartArrayHtml()`, but chainable on every supported PHP version:
+     * before PHP 8.4, `new SmartArrayHtml($data)->pluck('id')` is a syntax error without
+     * wrapping parentheses; `SmartArrayHtml::new($data)->pluck('id')` works everywhere.
+     *
+     *     $users = SmartArrayHtml::new($records)->indexBy('user_id');
+     *
      * @param array $array The input array to convert
      * @param array|bool $properties Optional properties to pass to the constructor (legacy boolean handled by the constructor)
      * @return static A new SmartArrayHtml instance

tests/Unit/CreationTest.php

@@ -113,8 +113,8 @@ public function testConstructorRejectsUnsupportedValues(string $class): void
     public static function contradictoryBoolProvider(): array
     {
         return [
-            'SmartArray with true'      => [SmartArray::class, true, 'Cannot create SmartArray with useSmartStrings=true. Use new SmartArrayHtml($data) instead.'],
-            'SmartArrayHtml with false' => [SmartArrayHtml::class, false, 'Cannot create SmartArrayHtml with useSmartStrings=false. Use new SmartArray($data) instead.'],
+            'SmartArray with true'      => [SmartArray::class, true, 'Cannot create SmartArray with useSmartStrings=true. Use SmartArrayHtml::new($data) instead.'],
+            'SmartArrayHtml with false' => [SmartArrayHtml::class, false, 'Cannot create SmartArrayHtml with useSmartStrings=false. Use SmartArray::new($data) instead.'],
         ];
     }