feat(VariableComment): Allow more complex PHPStan type annotations (#3355543)

Author: klausi

coder_sniffer/Drupal/Sniffs/Commenting/FunctionCommentSniff.php

@@ -687,6 +687,12 @@ protected function processParams(File $phpcsFile, $stackPtr, $commentStart)
                 $checkPos++;
             }
 
+            // Support variadic arguments.
+            if (preg_match('/(\s+)\.{3}$/', $param['type'], $matches) === 1) {
+                $param['type_space'] = strlen($matches[1]);
+                $param['type']       = preg_replace('/\s+\.{3}$/', '', $param['type']);
+            }
+
             // Check the param type value. This could also be multiple parameter
             // types separated by '|'.
             $typeNames      = explode('|', $param['type']);
@@ -697,12 +703,6 @@ protected function processParams(File $phpcsFile, $stackPtr, $commentStart)
 
             $suggestedType = implode('|', $suggestedNames);
 
-            // Support variadic arguments.
-            if (preg_match('/(\s+)\.{3}$/', $param['type'], $matches) === 1) {
-                $param['type_space'] = strlen($matches[1]);
-                $param['type']       = preg_replace('/\s+\.{3}$/', '', $param['type']);
-            }
-
             if (preg_match('/\s/', $param['type']) === 1) {
                 // Do not check PHPStan types that contain any kind of brackets.
                 // See https://phpstan.org/writing-php-code/phpdoc-types#general-arrays .
@@ -920,9 +920,10 @@ public static function suggestType($type)
             return $type;
         }
 
-        // Also allow "-" and "<>" for special type hints supported by PHPStan
+        // Also allow some more characters for special type hints supported by
+        // PHPStan:
         // https://phpstan.org/writing-php-code/phpdoc-types#basic-types .
-        $type = preg_replace('/[^a-zA-Z0-9_\\\[\]\-<>]/', '', $type);
+        $type = preg_replace('/[^a-zA-Z0-9_\\\[\]\-<> ,"\{\}\?\':\*]/', '', $type);
 
         return $type;
 

tests/Drupal/Commenting/FunctionCommentUnitTest.inc

@@ -305,8 +305,8 @@ function test25() {
 /**
  * Type declarations should not have any illegal characters.
  *
- * @param \Ille*al $var
- *   This asterisk does not belong here.
+ * @param \Ille§al $var
+ *   This character does not belong here.
  *
  * @return \Some/Namespace
  *   This should not have a forward slash.

tests/Drupal/Commenting/FunctionCommentUnitTest.inc.fixed

@@ -318,7 +318,7 @@ function test25() {
  * Type declarations should not have any illegal characters.
  *
  * @param \Illeal $var
- *   This asterisk does not belong here.
+ *   This character does not belong here.
  *
  * @return \SomeNamespace
  *   This should not have a forward slash.

tests/Drupal/Commenting/VariableCommentUnitTest.inc

@@ -63,4 +63,25 @@ class Test {
    */
   protected readonly string $readOnly;
 
+  /**
+   * PHPStan array annotation.
+   *
+   * @var array<int,array<int,int>>
+   */
+  protected array $arrayStructure;
+
+  /**
+   * PHPStan array shapes.
+   *
+   * @var array{'foo': int, "bar"?: string}
+   */
+  protected array $arrayShape;
+
+  /**
+   * PHPStan constant wildcard.
+   *
+   * @var Foo::*
+   */
+  protected string $constant;
+
 }

tests/Drupal/Commenting/VariableCommentUnitTest.inc.fixed

@@ -67,4 +67,25 @@ class Test {
    */
   protected readonly string $readOnly;
 
+  /**
+   * PHPStan array annotation.
+   *
+   * @var array<int,array<int,int>>
+   */
+  protected array $arrayStructure;
+
+  /**
+   * PHPStan array shapes.
+   *
+   * @var array{'foo': int, "bar"?: string}
+   */
+  protected array $arrayShape;
+
+  /**
+   * PHPStan constant wildcard.
+   *
+   * @var Foo::*
+   */
+  protected string $constant;
+
 }