Skip to content

Commit 95052fc

Browse files
klausiklausi
authored
feat(FunctionComment): Allow PHPStan basic data types in doc comments (#3253472)
1 parent fdbc043 commit 95052fc

File tree

7 files changed

+216
-18
lines changed

7 files changed

+216
-18
lines changed

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

Lines changed: 22 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -56,10 +56,25 @@ class FunctionCommentSniff implements Sniff
5656
*/
5757
public $allowedTypes = [
5858
'array',
59+
'array-key',
60+
'bool',
61+
'callable',
62+
'double',
63+
'float',
64+
'int',
65+
'iterable',
5966
'mixed',
6067
'object',
6168
'resource',
6269
'callable',
70+
'true',
71+
'false',
72+
'null',
73+
'scalar',
74+
'stdClass',
75+
'\stdClass',
76+
'string',
77+
'void',
6378
];
6479

6580

@@ -276,10 +291,7 @@ protected function processReturn(File $phpcsFile, $stackPtr, $commentStart)
276291
}
277292
}//end if
278293

279-
if ($type === 'void') {
280-
$error = 'If there is no return value for a function, there must not be a @return tag.';
281-
$phpcsFile->addError($error, $return, 'VoidReturn');
282-
} else if ($type !== 'mixed') {
294+
if ($type !== 'mixed' && $type !== 'void') {
283295
// If return type is not void, there needs to be a return statement
284296
// somewhere in the function that returns something.
285297
if (isset($tokens[$stackPtr]['scope_closer']) === true) {
@@ -747,7 +759,7 @@ protected function processParams(File $phpcsFile, $stackPtr, $commentStart)
747759
if (count($typeNames) === 1 && $typeName === $suggestedName) {
748760
// Check type hint for array and custom type.
749761
$suggestedTypeHint = '';
750-
if (strpos($suggestedName, 'array') !== false) {
762+
if (strpos($suggestedName, 'array') !== false && $suggestedName !== 'array-key') {
751763
$suggestedTypeHint = 'array';
752764
} else if (strpos($suggestedName, 'callable') !== false) {
753765
$suggestedTypeHint = 'callable';
@@ -762,7 +774,7 @@ protected function processParams(File $phpcsFile, $stackPtr, $commentStart)
762774
if ($suggestedTypeHint !== '' && isset($realParams[$checkPos]) === true) {
763775
$typeHint = $realParams[$checkPos]['type_hint'];
764776
// Primitive type hints are allowed to be omitted.
765-
if ($typeHint === '' && in_array($suggestedTypeHint, ['string', 'int', 'float', 'bool']) === false) {
777+
if ($typeHint === '' && in_array($suggestedTypeHint, $this->allowedTypes) === false) {
766778
$error = 'Type hint "%s" missing for %s';
767779
$data = [
768780
$suggestedTypeHint,
@@ -789,12 +801,7 @@ protected function processParams(File $phpcsFile, $stackPtr, $commentStart)
789801
) {
790802
$typeHint = $realParams[$checkPos]['type_hint'];
791803
if ($typeHint !== ''
792-
&& $typeHint !== 'stdClass'
793-
&& $typeHint !== '\stdClass'
794-
// As of PHP 7.2, object is a valid type hint.
795-
&& $typeHint !== 'object'
796-
// As of PHP 8.0, mixed is a valid type hint.
797-
&& $typeHint !== 'mixed'
804+
&& in_array($typeHint, $this->allowedTypes) === false
798805
) {
799806
$error = 'Unknown type hint "%s" found for %s';
800807
$data = [
@@ -1000,7 +1007,9 @@ public static function suggestType($type)
10001007
return $type;
10011008
}
10021009

1003-
$type = preg_replace('/[^a-zA-Z0-9_\\\[\]]/', '', $type);
1010+
// Also allow "-" for special type hint "array-key" supported by PHPStan
1011+
// https://phpstan.org/writing-php-code/phpdoc-types#basic-types .
1012+
$type = preg_replace('/[^a-zA-Z0-9_\\\[\]\-]/', '', $type);
10041013

10051014
return $type;
10061015

‎tests/Drupal/Commenting/FunctionCommentUnitTest.inc‎

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -559,3 +559,99 @@ class Test41 {
559559
}
560560

561561
}
562+
563+
/**
564+
* Support for PHPStan basic types.
565+
*
566+
* @param int $param1
567+
* Integer.
568+
* @param string $param2
569+
* String.
570+
* @param array-key $param3
571+
* Array key.
572+
* @param bool $param4
573+
* Boolean.
574+
* @param true $param5
575+
* Boolean TRUE.
576+
* @param false $param6
577+
* Boolean FALSE.
578+
* @param null $param7
579+
* NULL.
580+
* @param float $param8
581+
* Float.
582+
* @param double $param9
583+
* Double.
584+
* @param scalar $param10
585+
* Scalar.
586+
* @param array $param11
587+
* Array.
588+
* @param iterable $param12
589+
* Iterable.
590+
* @param callable $param13
591+
* Callable.
592+
* @param resource $param14
593+
* Resource.
594+
* @param void $param15
595+
* Void.
596+
* @param object $param16
597+
* Object.
598+
*
599+
* @see https://phpstan.org/writing-php-code/phpdoc-types#basic-types
600+
*/
601+
function test_basic_types(int $param1, string $param2, mixed $param3, bool $param4, bool $param5, bool $param6, $param7, float $param8, $param9, $param10, array $param11, $param12, $param13, $param14, $param15, $param16) {
602+
603+
}
604+
605+
/**
606+
* @return int
607+
* Int.
608+
*/
609+
function test_return_int(): int {
610+
return 0;
611+
}
612+
613+
/**
614+
* @return int
615+
* Int
616+
*/
617+
function test_return_int2() {
618+
return 0;
619+
}
620+
621+
/**
622+
* @return string
623+
* String.
624+
*/
625+
function test_return_string(): string {
626+
return '';
627+
}
628+
629+
/**
630+
* @return string
631+
* String.
632+
*/
633+
function test_return_string2() {
634+
return '';
635+
}
636+
637+
/**
638+
* @return array-key
639+
* Array key.
640+
*/
641+
function test_return_array_key() {
642+
return '';
643+
}
644+
645+
/**
646+
* @return void
647+
* Void.
648+
*/
649+
function test_return_void() {
650+
}
651+
652+
/**
653+
* @return void
654+
* Void.
655+
*/
656+
function test_return_void2(): void {
657+
}

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

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -585,3 +585,99 @@ class Test41 {
585585
}
586586

587587
}
588+
589+
/**
590+
* Support for PHPStan basic types.
591+
*
592+
* @param int $param1
593+
* Integer.
594+
* @param string $param2
595+
* String.
596+
* @param array-key $param3
597+
* Array key.
598+
* @param bool $param4
599+
* Boolean.
600+
* @param true $param5
601+
* Boolean TRUE.
602+
* @param false $param6
603+
* Boolean FALSE.
604+
* @param null $param7
605+
* NULL.
606+
* @param float $param8
607+
* Float.
608+
* @param double $param9
609+
* Double.
610+
* @param scalar $param10
611+
* Scalar.
612+
* @param array $param11
613+
* Array.
614+
* @param iterable $param12
615+
* Iterable.
616+
* @param callable $param13
617+
* Callable.
618+
* @param resource $param14
619+
* Resource.
620+
* @param void $param15
621+
* Void.
622+
* @param object $param16
623+
* Object.
624+
*
625+
* @see https://phpstan.org/writing-php-code/phpdoc-types#basic-types
626+
*/
627+
function test_basic_types(int $param1, string $param2, mixed $param3, bool $param4, bool $param5, bool $param6, $param7, float $param8, $param9, $param10, array $param11, $param12, $param13, $param14, $param15, $param16) {
628+
629+
}
630+
631+
/**
632+
* @return int
633+
* Int.
634+
*/
635+
function test_return_int(): int {
636+
return 0;
637+
}
638+
639+
/**
640+
* @return int
641+
* Int
642+
*/
643+
function test_return_int2() {
644+
return 0;
645+
}
646+
647+
/**
648+
* @return string
649+
* String.
650+
*/
651+
function test_return_string(): string {
652+
return '';
653+
}
654+
655+
/**
656+
* @return string
657+
* String.
658+
*/
659+
function test_return_string2() {
660+
return '';
661+
}
662+
663+
/**
664+
* @return array-key
665+
* Array key.
666+
*/
667+
function test_return_array_key() {
668+
return '';
669+
}
670+
671+
/**
672+
* @return void
673+
* Void.
674+
*/
675+
function test_return_void() {
676+
}
677+
678+
/**
679+
* @return void
680+
* Void.
681+
*/
682+
function test_return_void2(): void {
683+
}

‎tests/Drupal/Commenting/FunctionCommentUnitTest.php‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -71,7 +71,6 @@ protected function getErrorList(string $testFile): array
7171
416 => 1,
7272
426 => 2,
7373
427 => 2,
74-
465 => 1,
7574
538 => 1,
7675
540 => 1,
7776
];

‎tests/Drupal/bad/BadUnitTest.php‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -307,7 +307,6 @@ protected function getErrorList(string $testFile): array
307307
566 => 3,
308308
575 => 1,
309309
578 => 2,
310-
581 => 1,
311310
588 => 1,
312311
590 => 1,
313312
592 => 1,
@@ -358,7 +357,6 @@ protected function getErrorList(string $testFile): array
358357
750 => 1,
359358
756 => 1,
360359
765 => 1,
361-
775 => 1,
362360
791 => 1,
363361
795 => 4,
364362
796 => 1,

‎tests/Drupal/bad/bad.php‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -770,7 +770,7 @@ function test25() {
770770
}
771771

772772
/**
773-
* Void returns are not allowed.
773+
* Void returns are allowed.
774774
*
775775
* @return void
776776
* Description.

‎tests/Drupal/bad/bad.php.fixed‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -809,7 +809,7 @@ function test25() {
809809
}
810810

811811
/**
812-
* Void returns are not allowed.
812+
* Void returns are allowed.
813813
*
814814
* @return void
815815
* Description.

0 commit comments

Comments
 (0)