feat(FunctionComment): Allow PHPStan array shapes in doc data types (#3253472)

Author: klausi

coder_sniffer/Drupal/Sniffs/Commenting/FunctionCommentSniff.php

@@ -385,7 +385,10 @@ protected function processReturn(File $phpcsFile, $stackPtr, $commentStart)
                         if ($fix === true) {
                             $phpcsFile->fixer->replaceToken(($return + 2), $matches[1]);
                         }
-                    } else {
+
+                        // Do not check PHPStan array shapes from
+                        // https://phpstan.org/writing-php-code/phpdoc-types#general-arrays .
+                    } else if (strpos($type, 'array') === false) {
                         $error = 'Return type "%s" must not contain spaces';
                         $data  = [$type];
                         $phpcsFile->addError($error, $return, 'ReturnTypeSpaces', $data);
@@ -729,9 +732,13 @@ protected function processParams(File $phpcsFile, $stackPtr, $commentStart)
             }
 
             if (preg_match('/\s/', $param['type']) === 1) {
-                $error = 'Parameter type "%s" must not contain spaces';
-                $data  = [$param['type']];
-                $phpcsFile->addError($error, $param['tag'], 'ParamTypeSpaces', $data);
+                // Do not check PHPStan array shapes from
+                // https://phpstan.org/writing-php-code/phpdoc-types#general-arrays .
+                if (strpos($param['type'], 'array') === false) {
+                    $error = 'Parameter type "%s" must not contain spaces';
+                    $data  = [$param['type']];
+                    $phpcsFile->addError($error, $param['tag'], 'ParamTypeSpaces', $data);
+                }
             } else if ($param['type'] !== $suggestedType) {
                 $error = 'Expected "%s" but found "%s" for parameter type';
                 $data  = [
@@ -745,7 +752,7 @@ protected function processParams(File $phpcsFile, $stackPtr, $commentStart)
                     $content .= $param['var'];
                     $phpcsFile->fixer->replaceToken(($param['tag'] + 2), $content);
                 }
-            }
+            }//end if
 
             $suggestedName = '';
             $typeName      = '';
@@ -1007,9 +1014,9 @@ public static function suggestType($type)
             return $type;
         }
 
-        // Also allow "-" for special type hint "array-key" supported by PHPStan
+        // Also allow "-" and "<>" 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

@@ -655,3 +655,62 @@ function test_return_void() {
  */
 function test_return_void2(): void {
 }
+
+/**
+ * PHPStan: General arrays.
+ *
+ * @param Type[] $param1
+ *   Parameter.
+ * @param array<Type> $param2
+ *   Parameter.
+ * @param array<int, Type> $param3
+ *   Parameter.
+ * @param non-empty-array<Type> $param4
+ *   Parameter.
+ * @param non-empty-array<int, Type> $param5
+ *   Parameter.
+ *
+ * @see https://phpstan.org/writing-php-code/phpdoc-types#general-arrays
+ */
+function test_arrays(array $param1, array $param2, array $param3, array $param4, array $param5) {
+}
+
+/**
+ * @return Type[]
+ *   Square brackets.
+ */
+function test_return_type_array(): array {
+  return [];
+}
+
+/**
+ * @return array<Type>
+ *   Arrow brackets.
+ */
+function test_return_arrow_array(): array {
+  return [];
+}
+
+/**
+ * @return array<int, Type>
+ *   Keyed array.
+ */
+function test_return_keyed_array(): array {
+  return [];
+}
+
+/**
+ * @return non-empty-array<Type>
+ *   Non empty array with type.
+ */
+function test_return_non_empty_array(): array {
+  return [new Type()];
+}
+
+/**
+ * @return non-empty-array<int, Type>
+ *   Non empty keyed array with type.
+ */
+function test_return_non_empty_keyed_array(): array {
+  return [0 => new Type()];
+}

tests/Drupal/Commenting/FunctionCommentUnitTest.inc.fixed

@@ -681,3 +681,62 @@ function test_return_void() {
  */
 function test_return_void2(): void {
 }
+
+/**
+ * PHPStan: General arrays.
+ *
+ * @param Type[] $param1
+ *   Parameter.
+ * @param array<Type> $param2
+ *   Parameter.
+ * @param array<int, Type> $param3
+ *   Parameter.
+ * @param non-empty-array<Type> $param4
+ *   Parameter.
+ * @param non-empty-array<int, Type> $param5
+ *   Parameter.
+ *
+ * @see https://phpstan.org/writing-php-code/phpdoc-types#general-arrays
+ */
+function test_arrays(array $param1, array $param2, array $param3, array $param4, array $param5) {
+}
+
+/**
+ * @return Type[]
+ *   Square brackets.
+ */
+function test_return_type_array(): array {
+  return [];
+}
+
+/**
+ * @return array<Type>
+ *   Arrow brackets.
+ */
+function test_return_arrow_array(): array {
+  return [];
+}
+
+/**
+ * @return array<int, Type>
+ *   Keyed array.
+ */
+function test_return_keyed_array(): array {
+  return [];
+}
+
+/**
+ * @return non-empty-array<Type>
+ *   Non empty array with type.
+ */
+function test_return_non_empty_array(): array {
+  return [new Type()];
+}
+
+/**
+ * @return non-empty-array<int, Type>
+ *   Non empty keyed array with type.
+ */
+function test_return_non_empty_keyed_array(): array {
+  return [0 => new Type()];
+}