feat(FunctionComment): Allow advanced array shapes and integer ranges as doc data types (#193)

coder_sniffer/Drupal/Sniffs/Commenting/FunctionCommentSniff.php

@@ -62,6 +62,8 @@ class FunctionCommentSniff implements Sniff
         'double',
         'float',
         'int',
+        'positive-int',
+        'negative-int',
         'iterable',
         'mixed',
         'object',
@@ -386,9 +388,9 @@ class FunctionCommentSniff implements Sniff
                             $phpcsFile->fixer->replaceToken(($return + 2), $matches[1]);
                         }
 
-                        // Do not check PHPStan array shapes from
-                        // https://phpstan.org/writing-php-code/phpdoc-types#general-arrays .
-                    } else if (strpos($type, 'array') === false) {
+                        // Do not check PHPStan types that contain any kind of brackets.
+                        // See https://phpstan.org/writing-php-code/phpdoc-types#general-arrays .
+                    } else if (preg_match('/[<\[\{\(]/', $type) === 0) {
                         $error = 'Return type "%s" must not contain spaces';
                         $data  = [$type];
                         $phpcsFile->addError($error, $return, 'ReturnTypeSpaces', $data);
@@ -732,9 +734,9 @@ class FunctionCommentSniff implements Sniff
             }
 
             if (preg_match('/\s/', $param['type']) === 1) {
-                // Do not check PHPStan array shapes from
-                // https://phpstan.org/writing-php-code/phpdoc-types#general-arrays .
-                if (strpos($param['type'], 'array') === false) {
+                // Do not check PHPStan types that contain any kind of brackets.
+                // See https://phpstan.org/writing-php-code/phpdoc-types#general-arrays .
+                if (preg_match('/[<\[\{\(]/', $param['type']) === 0) {
                     $error = 'Parameter type "%s" must not contain spaces';
                     $data  = [$param['type']];
                     $phpcsFile->addError($error, $param['tag'], 'ParamTypeSpaces', $data);

tests/Drupal/Commenting/FunctionCommentUnitTest.inc

@@ -714,3 +714,111 @@ function test_return_non_empty_array(): array {
 function test_return_non_empty_keyed_array(): array {
   return [0 => new Type()];
 }
+
+/**
+ * PHPStan: Array shapes.
+ *
+ * @param array{'foo': int, "bar": string} $param1
+ *   Parameter.
+ * @param array{0: int, 1?: int} $param2
+ *   Parameter.
+ * @param array{int, int} $param3
+ *   Parameter.
+ * @param array{foo: int, bar: string} $param4
+ *   Parameter.
+ *
+ * @see https://phpstan.org/writing-php-code/phpdoc-types#array-shapes
+ */
+function test_advanced_array_shapes(array $param1, array $param2, array $param3, array $param4) {
+}
+
+/**
+ * @return array{'foo': int, "bar": string}
+ *   Array.
+ */
+function test_return_array_shape(): array {
+  return [];
+}
+
+/**
+ * @return array{0: int, 1?: int}
+ *   Array.
+ */
+function test_return_array_shape_int(): array {
+  return [];
+}
+
+/**
+ * @return array{int, int}
+ *   Array.
+ */
+function test_return_array_shape_nokey(): array {
+  return [];
+}
+
+/**
+ * @return array{foo: int, bar: string}
+ *   Array.
+ */
+function test_return_array_shape_noquote(): array {
+  return [];
+}
+
+/**
+ * PHPStan: Integer ranges.
+ *
+ * @param positive-int $param1
+ *   Parameter.
+ * @param negative-int $param2
+ *   Parameter.
+ * @param int<0, 100> $param3
+ *   Parameter.
+ * @param int<min, 100> $param4
+ *   Parameter.
+ * @param int<50, max> $param5
+ *   Parameter.
+ *
+ * @see https://phpstan.org/writing-php-code/phpdoc-types#integer-ranges
+ */
+function test_integer_ranges(int $param1, int $param2, int $param3, int $param4, int $param5) {
+}
+
+/**
+ * @return positive-int
+ *   Integer.
+ */
+function test_return_positive_integer(): int {
+  return 1;
+}
+
+/**
+ * @return negative-int
+ *   Integer.
+ */
+function test_return_negative_integer(): int {
+  return -1;
+}
+
+/**
+ * @return int<0, 100>
+ *   Integer.
+ */
+function test_return_integer_range(): int {
+  return 0;
+}
+
+/**
+ * @return int<min, 100>
+ *   Integer.
+ */
+function test_return_integer_min(): int {
+  return 0;
+}
+
+/**
+ * @return int<50, max>
+ *   Integer.
+ */
+function test_return_integer_max(): int {
+  return 50;
+}

tests/Drupal/Commenting/FunctionCommentUnitTest.inc.fixed

@@ -740,3 +740,111 @@ function test_return_non_empty_array(): array {
 function test_return_non_empty_keyed_array(): array {
   return [0 => new Type()];
 }
+
+/**
+ * PHPStan: Array shapes.
+ *
+ * @param array{'foo': int, "bar": string} $param1
+ *   Parameter.
+ * @param array{0: int, 1?: int} $param2
+ *   Parameter.
+ * @param array{int, int} $param3
+ *   Parameter.
+ * @param array{foo: int, bar: string} $param4
+ *   Parameter.
+ *
+ * @see https://phpstan.org/writing-php-code/phpdoc-types#array-shapes
+ */
+function test_advanced_array_shapes(array $param1, array $param2, array $param3, array $param4) {
+}
+
+/**
+ * @return array{'foo': int, "bar": string}
+ *   Array.
+ */
+function test_return_array_shape(): array {
+  return [];
+}
+
+/**
+ * @return array{0: int, 1?: int}
+ *   Array.
+ */
+function test_return_array_shape_int(): array {
+  return [];
+}
+
+/**
+ * @return array{int, int}
+ *   Array.
+ */
+function test_return_array_shape_nokey(): array {
+  return [];
+}
+
+/**
+ * @return array{foo: int, bar: string}
+ *   Array.
+ */
+function test_return_array_shape_noquote(): array {
+  return [];
+}
+
+/**
+ * PHPStan: Integer ranges.
+ *
+ * @param positive-int $param1
+ *   Parameter.
+ * @param negative-int $param2
+ *   Parameter.
+ * @param int<0, 100> $param3
+ *   Parameter.
+ * @param int<min, 100> $param4
+ *   Parameter.
+ * @param int<50, max> $param5
+ *   Parameter.
+ *
+ * @see https://phpstan.org/writing-php-code/phpdoc-types#integer-ranges
+ */
+function test_integer_ranges(int $param1, int $param2, int $param3, int $param4, int $param5) {
+}
+
+/**
+ * @return positive-int
+ *   Integer.
+ */
+function test_return_positive_integer(): int {
+  return 1;
+}
+
+/**
+ * @return negative-int
+ *   Integer.
+ */
+function test_return_negative_integer(): int {
+  return -1;
+}
+
+/**
+ * @return int<0, 100>
+ *   Integer.
+ */
+function test_return_integer_range(): int {
+  return 0;
+}
+
+/**
+ * @return int<min, 100>
+ *   Integer.
+ */
+function test_return_integer_min(): int {
+  return 0;
+}
+
+/**
+ * @return int<50, max>
+ *   Integer.
+ */
+function test_return_integer_max(): int {
+  return 50;
+}