Skip to content

Commit 0714066

Browse files
klausiklausi
authored
feat(FunctionComment): Allow advanced array shapes and integer ranges as doc data types (#193)
1 parent 4ee6a35 commit 0714066

File tree

3 files changed

+224
-6
lines changed

3 files changed

+224
-6
lines changed

‎coder_sniffer/Drupal/Sniffs/Commenting/FunctionCommentSniff.php

Lines changed: 8 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -62,6 +62,8 @@ class FunctionCommentSniff implements Sniff
6262
'double',
6363
'float',
6464
'int',
65+
'positive-int',
66+
'negative-int',
6567
'iterable',
6668
'mixed',
6769
'object',
@@ -386,9 +388,9 @@ protected function processReturn(File $phpcsFile, $stackPtr, $commentStart)
386388
$phpcsFile->fixer->replaceToken(($return + 2), $matches[1]);
387389
}
388390

389-
// Do not check PHPStan array shapes from
390-
// https://phpstan.org/writing-php-code/phpdoc-types#general-arrays .
391-
} else if (strpos($type, 'array') === false) {
391+
// Do not check PHPStan types that contain any kind of brackets.
392+
// See https://phpstan.org/writing-php-code/phpdoc-types#general-arrays .
393+
} else if (preg_match('/[<\[\{\(]/', $type) === 0) {
392394
$error = 'Return type "%s" must not contain spaces';
393395
$data = [$type];
394396
$phpcsFile->addError($error, $return, 'ReturnTypeSpaces', $data);
@@ -732,9 +734,9 @@ protected function processParams(File $phpcsFile, $stackPtr, $commentStart)
732734
}
733735

734736
if (preg_match('/\s/', $param['type']) === 1) {
735-
// Do not check PHPStan array shapes from
736-
// https://phpstan.org/writing-php-code/phpdoc-types#general-arrays .
737-
if (strpos($param['type'], 'array') === false) {
737+
// Do not check PHPStan types that contain any kind of brackets.
738+
// See https://phpstan.org/writing-php-code/phpdoc-types#general-arrays .
739+
if (preg_match('/[<\[\{\(]/', $param['type']) === 0) {
738740
$error = 'Parameter type "%s" must not contain spaces';
739741
$data = [$param['type']];
740742
$phpcsFile->addError($error, $param['tag'], 'ParamTypeSpaces', $data);

‎tests/Drupal/Commenting/FunctionCommentUnitTest.inc

Lines changed: 108 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -714,3 +714,111 @@ function test_return_non_empty_array(): array {
714714
function test_return_non_empty_keyed_array(): array {
715715
return [0 => new Type()];
716716
}
717+
718+
/**
719+
* PHPStan: Array shapes.
720+
*
721+
* @param array{'foo': int, "bar": string} $param1
722+
* Parameter.
723+
* @param array{0: int, 1?: int} $param2
724+
* Parameter.
725+
* @param array{int, int} $param3
726+
* Parameter.
727+
* @param array{foo: int, bar: string} $param4
728+
* Parameter.
729+
*
730+
* @see https://phpstan.org/writing-php-code/phpdoc-types#array-shapes
731+
*/
732+
function test_advanced_array_shapes(array $param1, array $param2, array $param3, array $param4) {
733+
}
734+
735+
/**
736+
* @return array{'foo': int, "bar": string}
737+
* Array.
738+
*/
739+
function test_return_array_shape(): array {
740+
return [];
741+
}
742+
743+
/**
744+
* @return array{0: int, 1?: int}
745+
* Array.
746+
*/
747+
function test_return_array_shape_int(): array {
748+
return [];
749+
}
750+
751+
/**
752+
* @return array{int, int}
753+
* Array.
754+
*/
755+
function test_return_array_shape_nokey(): array {
756+
return [];
757+
}
758+
759+
/**
760+
* @return array{foo: int, bar: string}
761+
* Array.
762+
*/
763+
function test_return_array_shape_noquote(): array {
764+
return [];
765+
}
766+
767+
/**
768+
* PHPStan: Integer ranges.
769+
*
770+
* @param positive-int $param1
771+
* Parameter.
772+
* @param negative-int $param2
773+
* Parameter.
774+
* @param int<0, 100> $param3
775+
* Parameter.
776+
* @param int<min, 100> $param4
777+
* Parameter.
778+
* @param int<50, max> $param5
779+
* Parameter.
780+
*
781+
* @see https://phpstan.org/writing-php-code/phpdoc-types#integer-ranges
782+
*/
783+
function test_integer_ranges(int $param1, int $param2, int $param3, int $param4, int $param5) {
784+
}
785+
786+
/**
787+
* @return positive-int
788+
* Integer.
789+
*/
790+
function test_return_positive_integer(): int {
791+
return 1;
792+
}
793+
794+
/**
795+
* @return negative-int
796+
* Integer.
797+
*/
798+
function test_return_negative_integer(): int {
799+
return -1;
800+
}
801+
802+
/**
803+
* @return int<0, 100>
804+
* Integer.
805+
*/
806+
function test_return_integer_range(): int {
807+
return 0;
808+
}
809+
810+
/**
811+
* @return int<min, 100>
812+
* Integer.
813+
*/
814+
function test_return_integer_min(): int {
815+
return 0;
816+
}
817+
818+
/**
819+
* @return int<50, max>
820+
* Integer.
821+
*/
822+
function test_return_integer_max(): int {
823+
return 50;
824+
}

‎tests/Drupal/Commenting/FunctionCommentUnitTest.inc.fixed

Lines changed: 108 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -740,3 +740,111 @@ function test_return_non_empty_array(): array {
740740
function test_return_non_empty_keyed_array(): array {
741741
return [0 => new Type()];
742742
}
743+
744+
/**
745+
* PHPStan: Array shapes.
746+
*
747+
* @param array{'foo': int, "bar": string} $param1
748+
* Parameter.
749+
* @param array{0: int, 1?: int} $param2
750+
* Parameter.
751+
* @param array{int, int} $param3
752+
* Parameter.
753+
* @param array{foo: int, bar: string} $param4
754+
* Parameter.
755+
*
756+
* @see https://phpstan.org/writing-php-code/phpdoc-types#array-shapes
757+
*/
758+
function test_advanced_array_shapes(array $param1, array $param2, array $param3, array $param4) {
759+
}
760+
761+
/**
762+
* @return array{'foo': int, "bar": string}
763+
* Array.
764+
*/
765+
function test_return_array_shape(): array {
766+
return [];
767+
}
768+
769+
/**
770+
* @return array{0: int, 1?: int}
771+
* Array.
772+
*/
773+
function test_return_array_shape_int(): array {
774+
return [];
775+
}
776+
777+
/**
778+
* @return array{int, int}
779+
* Array.
780+
*/
781+
function test_return_array_shape_nokey(): array {
782+
return [];
783+
}
784+
785+
/**
786+
* @return array{foo: int, bar: string}
787+
* Array.
788+
*/
789+
function test_return_array_shape_noquote(): array {
790+
return [];
791+
}
792+
793+
/**
794+
* PHPStan: Integer ranges.
795+
*
796+
* @param positive-int $param1
797+
* Parameter.
798+
* @param negative-int $param2
799+
* Parameter.
800+
* @param int<0, 100> $param3
801+
* Parameter.
802+
* @param int<min, 100> $param4
803+
* Parameter.
804+
* @param int<50, max> $param5
805+
* Parameter.
806+
*
807+
* @see https://phpstan.org/writing-php-code/phpdoc-types#integer-ranges
808+
*/
809+
function test_integer_ranges(int $param1, int $param2, int $param3, int $param4, int $param5) {
810+
}
811+
812+
/**
813+
* @return positive-int
814+
* Integer.
815+
*/
816+
function test_return_positive_integer(): int {
817+
return 1;
818+
}
819+
820+
/**
821+
* @return negative-int
822+
* Integer.
823+
*/
824+
function test_return_negative_integer(): int {
825+
return -1;
826+
}
827+
828+
/**
829+
* @return int<0, 100>
830+
* Integer.
831+
*/
832+
function test_return_integer_range(): int {
833+
return 0;
834+
}
835+
836+
/**
837+
* @return int<min, 100>
838+
* Integer.
839+
*/
840+
function test_return_integer_min(): int {
841+
return 0;
842+
}
843+
844+
/**
845+
* @return int<50, max>
846+
* Integer.
847+
*/
848+
function test_return_integer_max(): int {
849+
return 50;
850+
}

0 commit comments

Comments
 (0)