From f63aa0ca8a9eb4e45bae4edc51e3d15a5cd4def4 Mon Sep 17 00:00:00 2001
From: jrfnl <jrfnl@users.noreply.github.com>
Date: Sun, 17 Nov 2024 00:52:19 +0100
Subject: [PATCH] Ruleset: hard deprecate use of the old property array format

This format was (soft) deprecated in PHPCS 3.3.0 (June 2018) and it is expected that most rulesets will have been updated.

With the new "error handling" functionality in the Ruleset class in place (PR 857), the old format can now be hard deprecated to make users who haven't updated their rulesets yet, aware of the upcoming removal of support for the old array format.

Refs:
* https://github.com/PHPCSStandards/PHP_CodeSniffer/releases/tag/3.3.0
* squizlabs/PHP_CodeSniffer 1665

Closes 693
---
 src/Ruleset.php                               |  9 ++++-
 .../Core/Ruleset/PropertyTypeHandlingTest.php | 34 ++++++++++++++++++-
 2 files changed, 41 insertions(+), 2 deletions(-)

diff --git a/src/Ruleset.php b/src/Ruleset.php
index b6279bf9f3..b87c6be89e 100644
--- a/src/Ruleset.php
+++ b/src/Ruleset.php
@@ -1219,7 +1219,14 @@ private function processRule($rule, $newSniffs, $depth=0)
                             }
 
                             $printValue = rtrim($printValue, ',');
-                        } else {
+                        } else if (isset($prop['value']) === true) {
+                            $message  = 'Passing an array of values to a property using a comma-separated string'.PHP_EOL;
+                            $message .= 'was deprecated in PHP_CodeSniffer 3.3.0. Support will be removed in PHPCS 4.0.0.'.PHP_EOL;
+                            $message .= "The deprecated syntax was used for property \"$name\"".PHP_EOL;
+                            $message .= "for sniff \"$code\".".PHP_EOL;
+                            $message .= 'Pass array values via <element [key="..." ]value="..."> nodes instead.';
+                            $this->msgCache->add($message, MessageCollector::DEPRECATED);
+
                             $value      = (string) $prop['value'];
                             $printValue = $value;
                             if ($value !== '') {
diff --git a/tests/Core/Ruleset/PropertyTypeHandlingTest.php b/tests/Core/Ruleset/PropertyTypeHandlingTest.php
index 346914b142..1db15aa5d2 100644
--- a/tests/Core/Ruleset/PropertyTypeHandlingTest.php
+++ b/tests/Core/Ruleset/PropertyTypeHandlingTest.php
@@ -38,6 +38,35 @@ final class PropertyTypeHandlingTest extends TestCase
     const SNIFF_CLASS = 'Fixtures\\TestStandard\\Sniffs\\SetProperty\\PropertyTypeHandlingSniff';
 
 
+    /**
+     * Verify a deprecation notice is shown when an array property is set from the ruleset using a comma-separated string.
+     *
+     * Support for this format was (soft) deprecated in PHPCS 3.3.0.
+     *
+     * @return void
+     */
+    public function testUsingOldSchoolArrayFormatShowsDeprecationNotice()
+    {
+        $regex  = '`^(';
+        $regex .= 'DEPRECATED: Passing an array of values to a property using a comma-separated string\R';
+        $regex .= 'was deprecated in PHP_CodeSniffer 3\.3\.0\. Support will be removed in PHPCS 4\.0\.0\.\R';
+        $regex .= 'The deprecated syntax was used for property "expectsOldSchool(?:EmptyArray|ArrayWith(?:Extended|Only)?(?:KeysAnd)?Values)"\R';
+        $regex .= 'for sniff "';
+        $regex .= '(?:\./tests/Core/Ruleset/Fixtures/TestStandard/Sniffs/SetProperty/PropertyTypeHandlingSniff\.php|TestStandard\.SetProperty\.PropertyTypeHandling)';
+        $regex .= '"\.\R';
+        $regex .= 'Pass array values via <element \[key="\.\.\." \]value="\.\.\."> nodes instead\.\R';
+        $regex .= '){14}\R$`';
+
+        $this->expectOutputRegex($regex);
+
+        // Set up the ruleset.
+        $standard = __DIR__.'/PropertyTypeHandlingTest.xml';
+        $config   = new ConfigDouble(["--standard=$standard"]);
+        new Ruleset($config);
+
+    }//end testUsingOldSchoolArrayFormatShowsDeprecationNotice()
+
+
     /**
      * Test the value type handling for properties set via a ruleset.
      *
@@ -234,6 +263,9 @@ public static function dataArrayPropertyExtending()
     /**
      * Test Helper.
      *
+     * Note: the deprecations for using comma-separated string to pass an array, are silenced in this helper
+     * as that's not what's being tested here.
+     *
      * @see self::testTypeHandlingWhenSetViaRuleset()
      *
      * @return \PHP_CodeSniffer\Sniffs\Sniff
@@ -245,7 +277,7 @@ private function getSniffObjectForRuleset()
         if (isset($sniffObject) === false) {
             // Set up the ruleset.
             $standard = __DIR__.'/PropertyTypeHandlingTest.xml';
-            $config   = new ConfigDouble(["--standard=$standard"]);
+            $config   = new ConfigDouble(["--standard=$standard", '-q']);
             $ruleset  = new Ruleset($config);
 
             // Verify that our target sniff has been registered.