Skip to content

Add generic support to @method definitions #160

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 7 commits into from
Dec 7, 2022
Merged

Add generic support to @method definitions #160

Show file tree
Hide file tree
Changes from 6 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
93e9088
Add generic support to `@method` definitions
tyabu12 Nov 1, 2022
6e9c776
Avoid BC break and reuse TemplateTagValueNode
tyabu12 Nov 1, 2022
e661949
Fix PHP 7.2 lint
tyabu12 Nov 1, 2022
ba315ab
Fix PHP 7.2 lint again
tyabu12 Nov 1, 2022
cbcd76b
Fix PHP 7.2 lint again 2
tyabu12 Nov 1, 2022
6838eed
Fix coding standard errors
tyabu12 Nov 1, 2022
96d3a2f
Reuse parseTemplateTagValue
tyabu12 Nov 1, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 8 additions & 2 deletions src/Ast/PhpDoc/MethodTagValueNode.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@

use PHPStan\PhpDocParser\Ast\NodeAttributes;
use PHPStan\PhpDocParser\Ast\Type\TypeNode;
use function count;
use function implode;

class MethodTagValueNode implements PhpDocTagValueNode
Expand All @@ -20,19 +21,23 @@ class MethodTagValueNode implements PhpDocTagValueNode
/** @var string */
public $methodName;

/** @var TemplateTagValueNode[] */
public $templateTypes;

/** @var MethodTagValueParameterNode[] */
public $parameters;

/** @var string (may be empty) */
public $description;

public function __construct(bool $isStatic, ?TypeNode $returnType, string $methodName, array $parameters, string $description)
public function __construct(bool $isStatic, ?TypeNode $returnType, string $methodName, array $parameters, string $description, array $templateTypes = [])
{
$this->isStatic = $isStatic;
$this->returnType = $returnType;
$this->methodName = $methodName;
$this->parameters = $parameters;
$this->description = $description;
$this->templateTypes = $templateTypes;
}


Expand All @@ -42,7 +47,8 @@ public function __toString(): string
$returnType = $this->returnType !== null ? "{$this->returnType} " : '';
$parameters = implode(', ', $this->parameters);
$description = $this->description !== '' ? " {$this->description}" : '';
return "{$static}{$returnType}{$this->methodName}({$parameters}){$description}";
$templateTypes = count($this->templateTypes) > 0 ? '<' . implode(', ', $this->templateTypes) . '>' : '';
return "{$static}{$returnType}{$this->methodName}{$templateTypes}({$parameters}){$description}";
}

}
29 changes: 28 additions & 1 deletion src/Parser/PhpDocParser.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -346,6 +346,14 @@ private function parseMethodTagValue(TokenIterator $tokens): Ast\PhpDoc\MethodTa
exit;
}

$templateTypes = [];
if ($tokens->tryConsumeTokenType(Lexer::TOKEN_OPEN_ANGLE_BRACKET)) {
do {
$templateTypes[] = $this->parseMethodTagValueTemplateType($tokens);
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could we call the already existing parseTemplateTagValue?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@ondrejmirtes
I fixed it.
parseTemplateTagValue also parse description text, so it was necessary to add the flag parameter $parseDescription.

} while ($tokens->tryConsumeTokenType(Lexer::TOKEN_COMMA));
$tokens->consumeTokenType(Lexer::TOKEN_CLOSE_ANGLE_BRACKET);
}

$parameters = [];
$tokens->consumeTokenType(Lexer::TOKEN_OPEN_PARENTHESES);
if (!$tokens->isCurrentTokenType(Lexer::TOKEN_CLOSE_PARENTHESES)) {
Expand All @@ -357,9 +365,28 @@ private function parseMethodTagValue(TokenIterator $tokens): Ast\PhpDoc\MethodTa
$tokens->consumeTokenType(Lexer::TOKEN_CLOSE_PARENTHESES);

$description = $this->parseOptionalDescription($tokens);
return new Ast\PhpDoc\MethodTagValueNode($isStatic, $returnType, $methodName, $parameters, $description);
return new Ast\PhpDoc\MethodTagValueNode($isStatic, $returnType, $methodName, $parameters, $description, $templateTypes);
}

private function parseMethodTagValueTemplateType(TokenIterator $tokens): Ast\PhpDoc\TemplateTagValueNode
{
$name = $tokens->currentTokenValue();
$tokens->consumeTokenType(Lexer::TOKEN_IDENTIFIER);

if ($tokens->tryConsumeTokenValue('of') || $tokens->tryConsumeTokenValue('as')) {
$bound = $this->typeParser->parse($tokens);
} else {
$bound = null;
}

if ($tokens->tryConsumeTokenValue('=')) {
$default = $this->typeParser->parse($tokens);
} else {
$default = null;
}

return new Ast\PhpDoc\TemplateTagValueNode($name, $bound, '', $default);
}

private function parseMethodTagValueParameter(TokenIterator $tokens): Ast\PhpDoc\MethodTagValueParameterNode
{
Expand Down
133 changes: 133 additions & 0 deletions tests/PHPStan/Parser/PhpDocParserTest.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@
namespace PHPStan\PhpDocParser\Parser;

use Iterator;
use PHPStan\PhpDocParser\Ast\ConstExpr\ConstExprArrayItemNode;
use PHPStan\PhpDocParser\Ast\ConstExpr\ConstExprArrayNode;
use PHPStan\PhpDocParser\Ast\ConstExpr\ConstExprIntegerNode;
use PHPStan\PhpDocParser\Ast\ConstExpr\ConstExprStringNode;
Expand Down Expand Up @@ -44,6 +45,7 @@
use PHPStan\PhpDocParser\Ast\Type\ConstTypeNode;
use PHPStan\PhpDocParser\Ast\Type\GenericTypeNode;
use PHPStan\PhpDocParser\Ast\Type\IdentifierTypeNode;
use PHPStan\PhpDocParser\Ast\Type\NullableTypeNode;
use PHPStan\PhpDocParser\Ast\Type\OffsetAccessTypeNode;
use PHPStan\PhpDocParser\Ast\Type\UnionTypeNode;
use PHPStan\PhpDocParser\Lexer\Lexer;
Expand Down Expand Up @@ -2195,6 +2197,98 @@ public function provideMethodTagsData(): Iterator
),
]),
];

yield [
'OK non-static, with return type and parameter with generic type',
'/** @method ?T randomElement<T = string>(array<array-key, T> $array = [\'a\', \'b\']) */',
new PhpDocNode([
new PhpDocTagNode(
'@method',
new MethodTagValueNode(
false,
new NullableTypeNode(new IdentifierTypeNode('T')),
'randomElement',
[
new MethodTagValueParameterNode(
new GenericTypeNode(
new IdentifierTypeNode('array'),
[
new IdentifierTypeNode('array-key'),
new IdentifierTypeNode('T'),
]
),
false,
false,
'$array',
new ConstExprArrayNode([
new ConstExprArrayItemNode(
null,
new ConstExprStringNode('\'a\'')
),
new ConstExprArrayItemNode(
null,
new ConstExprStringNode('\'b\'')
),
])
),
],
'',
[
new TemplateTagValueNode(
'T',
null,
'',
new IdentifierTypeNode('string')
),
]
)
),
]),
];

yield [
'OK static, with return type and multiple parameters with generic type',
'/** @method static bool compare<T1, T2 of Bar, T3 as Baz>(T1 $t1, T2 $t2, T3 $t3) */',
new PhpDocNode([
new PhpDocTagNode(
'@method',
new MethodTagValueNode(
true,
new IdentifierTypeNode('bool'),
'compare',
[
new MethodTagValueParameterNode(
new IdentifierTypeNode('T1'),
false,
false,
'$t1',
null
),
new MethodTagValueParameterNode(
new IdentifierTypeNode('T2'),
false,
false,
'$t2',
null
),
new MethodTagValueParameterNode(
new IdentifierTypeNode('T3'),
false,
false,
'$t3',
null
),
],
'',
[
new TemplateTagValueNode('T1', null, ''),
new TemplateTagValueNode('T2', new IdentifierTypeNode('Bar'), ''),
new TemplateTagValueNode('T3', new IdentifierTypeNode('Baz'), ''),
]
)
),
]),
];
}


Expand Down Expand Up @@ -3072,6 +3166,45 @@ public function provideMultiLinePhpDocData(): array
),
]),
],
[
'OK with template method',
'/**
* @template TKey as array-key
* @template TValue
* @method TKey|null find(TValue $v) find index of $v
*/',
new PhpDocNode([
new PhpDocTagNode(
'@template',
new TemplateTagValueNode('TKey', new IdentifierTypeNode('array-key'), '')
),
new PhpDocTagNode(
'@template',
new TemplateTagValueNode('TValue', null, '')
),
new PhpDocTagNode(
'@method',
new MethodTagValueNode(
false,
new UnionTypeNode([
new IdentifierTypeNode('TKey'),
new IdentifierTypeNode('null'),
]),
'find',
[
new MethodTagValueParameterNode(
new IdentifierTypeNode('TValue'),
false,
false,
'$v',
null
),
],
'find index of $v'
)
),
]),
],
[
'OK with multiline conditional return type',
'/**
Expand Down