Skip to content

Commit d622b7c

Browse files
VincentLangletondrejmirtes
VincentLanglet
authored and
ondrejmirtes
committed
Add support for reference in phpdoc
1 parent da187fd commit d622b7c

File tree

4 files changed

+97
-4
lines changed

4 files changed

+97
-4
lines changed

‎doc/grammars/phpdoc-param.peg‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,12 @@
11
PhpDocParam
2-
= AnnotationName Type IsVariadic? ParameterName Description?
2+
= AnnotationName Type IsReference? IsVariadic? ParameterName Description?
33

44
AnnotationName
55
= '@param'
66

7+
IsReference
8+
= '&'
9+
710
IsVariaric
811
= '...'
912

‎src/Ast/PhpDoc/ParamTagValueNode.php‎

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,9 @@ class ParamTagValueNode implements PhpDocTagValueNode
1313
/** @var TypeNode */
1414
public $type;
1515

16+
/** @var bool */
17+
public $isReference;
18+
1619
/** @var bool */
1720
public $isVariadic;
1821

@@ -22,9 +25,10 @@ class ParamTagValueNode implements PhpDocTagValueNode
2225
/** @var string (may be empty) */
2326
public $description;
2427

25-
public function __construct(TypeNode $type, bool $isVariadic, string $parameterName, string $description)
28+
public function __construct(TypeNode $type, bool $isReference, bool $isVariadic, string $parameterName, string $description)
2629
{
2730
$this->type = $type;
31+
$this->isReference = $isReference;
2832
$this->isVariadic = $isVariadic;
2933
$this->parameterName = $parameterName;
3034
$this->description = $description;
@@ -33,8 +37,9 @@ public function __construct(TypeNode $type, bool $isVariadic, string $parameterN
3337

3438
public function __toString(): string
3539
{
40+
$reference = $this->isReference ? '&' : '';
3641
$variadic = $this->isVariadic ? '...' : '';
37-
return trim("{$this->type} {$variadic}{$this->parameterName} {$this->description}");
42+
return trim("{$this->type} {$reference}{$variadic}{$this->parameterName} {$this->description}");
3843
}
3944

4045
}

‎src/Parser/PhpDocParser.php‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -220,10 +220,11 @@ public function parseTagValue(TokenIterator $tokens, string $tag): Ast\PhpDoc\Ph
220220
private function parseParamTagValue(TokenIterator $tokens): Ast\PhpDoc\ParamTagValueNode
221221
{
222222
$type = $this->typeParser->parse($tokens);
223+
$isReference = $tokens->tryConsumeTokenType(Lexer::TOKEN_REFERENCE);
223224
$isVariadic = $tokens->tryConsumeTokenType(Lexer::TOKEN_VARIADIC);
224225
$parameterName = $this->parseRequiredVariableName($tokens);
225226
$description = $this->parseOptionalDescription($tokens);
226-
return new Ast\PhpDoc\ParamTagValueNode($type, $isVariadic, $parameterName, $description);
227+
return new Ast\PhpDoc\ParamTagValueNode($type, $isReference, $isVariadic, $parameterName, $description);
227228
}
228229

229230

‎tests/PHPStan/Parser/PhpDocParserTest.php‎

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -99,6 +99,7 @@ public function provideParamTagsData(): \Iterator
9999
new ParamTagValueNode(
100100
new IdentifierTypeNode('Foo'),
101101
false,
102+
false,
102103
'$foo',
103104
''
104105
)
@@ -115,6 +116,7 @@ public function provideParamTagsData(): \Iterator
115116
new ParamTagValueNode(
116117
new IdentifierTypeNode('Foo'),
117118
false,
119+
false,
118120
'$foo',
119121
'optional description'
120122
)
@@ -130,6 +132,7 @@ public function provideParamTagsData(): \Iterator
130132
'@param',
131133
new ParamTagValueNode(
132134
new IdentifierTypeNode('Foo'),
135+
false,
133136
true,
134137
'$foo',
135138
''
@@ -146,6 +149,75 @@ public function provideParamTagsData(): \Iterator
146149
'@param',
147150
new ParamTagValueNode(
148151
new IdentifierTypeNode('Foo'),
152+
false,
153+
true,
154+
'$foo',
155+
'optional description'
156+
)
157+
),
158+
]),
159+
];
160+
161+
yield [
162+
'OK reference without description',
163+
'/** @param Foo &$foo */',
164+
new PhpDocNode([
165+
new PhpDocTagNode(
166+
'@param',
167+
new ParamTagValueNode(
168+
new IdentifierTypeNode('Foo'),
169+
true,
170+
false,
171+
'$foo',
172+
''
173+
)
174+
),
175+
]),
176+
];
177+
178+
yield [
179+
'OK reference with description',
180+
'/** @param Foo &$foo optional description */',
181+
new PhpDocNode([
182+
new PhpDocTagNode(
183+
'@param',
184+
new ParamTagValueNode(
185+
new IdentifierTypeNode('Foo'),
186+
true,
187+
false,
188+
'$foo',
189+
'optional description'
190+
)
191+
),
192+
]),
193+
];
194+
195+
yield [
196+
'OK reference variadic without description',
197+
'/** @param Foo &...$foo */',
198+
new PhpDocNode([
199+
new PhpDocTagNode(
200+
'@param',
201+
new ParamTagValueNode(
202+
new IdentifierTypeNode('Foo'),
203+
true,
204+
true,
205+
'$foo',
206+
''
207+
)
208+
),
209+
]),
210+
];
211+
212+
yield [
213+
'OK reference variadic with description',
214+
'/** @param Foo &...$foo optional description */',
215+
new PhpDocNode([
216+
new PhpDocTagNode(
217+
'@param',
218+
new ParamTagValueNode(
219+
new IdentifierTypeNode('Foo'),
220+
true,
149221
true,
150222
'$foo',
151223
'optional description'
@@ -1827,6 +1899,7 @@ public function provideMultiLinePhpDocData(): array
18271899
new ParamTagValueNode(
18281900
new IdentifierTypeNode('Foo'),
18291901
false,
1902+
false,
18301903
'$foo',
18311904
'1st multi world description'
18321905
)
@@ -1836,6 +1909,7 @@ public function provideMultiLinePhpDocData(): array
18361909
new ParamTagValueNode(
18371910
new IdentifierTypeNode('Bar'),
18381911
false,
1912+
false,
18391913
'$bar',
18401914
'2nd multi world description'
18411915
)
@@ -1855,6 +1929,7 @@ public function provideMultiLinePhpDocData(): array
18551929
new ParamTagValueNode(
18561930
new IdentifierTypeNode('Foo'),
18571931
false,
1932+
false,
18581933
'$foo',
18591934
'1st multi world description
18601935
some text in the middle'
@@ -1865,6 +1940,7 @@ public function provideMultiLinePhpDocData(): array
18651940
new ParamTagValueNode(
18661941
new IdentifierTypeNode('Bar'),
18671942
false,
1943+
false,
18681944
'$bar',
18691945
'2nd multi world description'
18701946
)
@@ -1895,6 +1971,7 @@ public function provideMultiLinePhpDocData(): array
18951971
new ParamTagValueNode(
18961972
new IdentifierTypeNode('Foo'),
18971973
false,
1974+
false,
18981975
'$foo',
18991976
'1st multi world description with empty lines'
19001977
)
@@ -1909,6 +1986,7 @@ public function provideMultiLinePhpDocData(): array
19091986
new ParamTagValueNode(
19101987
new IdentifierTypeNode('Bar'),
19111988
false,
1989+
false,
19121990
'$bar',
19131991
'2nd multi world description with empty lines'
19141992
)
@@ -1942,6 +2020,7 @@ public function provideMultiLinePhpDocData(): array
19422020
new ParamTagValueNode(
19432021
new IdentifierTypeNode('int'),
19442022
false,
2023+
false,
19452024
'$foo',
19462025
'@param string $bar'
19472026
)
@@ -2857,6 +2936,7 @@ public function provideExtendsTagsData(): \Iterator
28572936
new ParamTagValueNode(
28582937
new IdentifierTypeNode('class-string'),
28592938
false,
2939+
false,
28602940
'$test',
28612941
''
28622942
)
@@ -2873,6 +2953,7 @@ public function provideExtendsTagsData(): \Iterator
28732953
new ParamTagValueNode(
28742954
new IdentifierTypeNode('class-string'),
28752955
false,
2956+
false,
28762957
'$test',
28772958
'some description'
28782959
)
@@ -3166,6 +3247,7 @@ public function provideRealWorldExampleData(): \Iterator
31663247
new ParamTagValueNode(
31673248
new IdentifierTypeNode('\Drupal\Core\Field\FieldStorageDefinitionInterface'),
31683249
false,
3250+
false,
31693251
'$field_definition',
31703252
''
31713253
)
@@ -3243,6 +3325,7 @@ public function provideRealWorldExampleData(): \Iterator
32433325
new ParamTagValueNode(
32443326
new IdentifierTypeNode('Request'),
32453327
false,
3328+
false,
32463329
'$request',
32473330
'- The request object'
32483331
)
@@ -3463,6 +3546,7 @@ public function dataParseTagValue(): array
34633546
new ParamTagValueNode(
34643547
new ConstTypeNode(new ConstFetchNode('DateTimeImmutable', 'ATOM')),
34653548
false,
3549+
false,
34663550
'$a',
34673551
''
34683552
),

0 commit comments

Comments
 (0)