Skip to content

Commit 4644f47

Browse files
fabpotfabpot
committed
feature symfony#52632 [PropertyInfo] Make PhpDocExtractor::getDocBlock() public (Nyholm)
This PR was squashed before being merged into the 7.1 branch. Discussion ---------- [PropertyInfo] Make `PhpDocExtractor::getDocBlock()` public | Q | A | ------------- | --- | Branch? | 7.1 | Bug fix? | no | New feature? | yes | Deprecations? | no | Issues | N/a | License | MIT Im parsing properties and I would love to find out what is in the doc block for a property. Help me figure out why it would be a bad idea to make this method public. Commits ------- 95f8c1d [PropertyInfo] Make `PhpDocExtractor::getDocBlock()` public
2 parents ca43978 + 95f8c1d commit 4644f47

File tree

6 files changed

+78
-10
lines changed

6 files changed

+78
-10
lines changed

‎src/Symfony/Component/PropertyInfo/CHANGELOG.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,11 @@
11
CHANGELOG
22
=========
33

4+
7.1
5+
---
6+
7+
* Introduce `PropertyDocBlockExtractorInterface` to extract a property's doc block
8+
49
6.4
510
---
611

‎src/Symfony/Component/PropertyInfo/Extractor/PhpDocExtractor.php‎

Lines changed: 13 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@
1818
use phpDocumentor\Reflection\Types\Context;
1919
use phpDocumentor\Reflection\Types\ContextFactory;
2020
use Symfony\Component\PropertyInfo\PropertyDescriptionExtractorInterface;
21+
use Symfony\Component\PropertyInfo\PropertyDocBlockExtractorInterface;
2122
use Symfony\Component\PropertyInfo\PropertyTypeExtractorInterface;
2223
use Symfony\Component\PropertyInfo\Type;
2324
use Symfony\Component\PropertyInfo\Util\PhpDocTypeHelper;
@@ -29,7 +30,7 @@
2930
*
3031
* @final
3132
*/
32-
class PhpDocExtractor implements PropertyDescriptionExtractorInterface, PropertyTypeExtractorInterface, ConstructorArgumentTypeExtractorInterface
33+
class PhpDocExtractor implements PropertyDescriptionExtractorInterface, PropertyTypeExtractorInterface, ConstructorArgumentTypeExtractorInterface, PropertyDocBlockExtractorInterface
3334
{
3435
public const PROPERTY = 0;
3536
public const ACCESSOR = 1;
@@ -74,7 +75,7 @@ public function __construct(DocBlockFactoryInterface $docBlockFactory = null, ar
7475
public function getShortDescription(string $class, string $property, array $context = []): ?string
7576
{
7677
/** @var $docBlock DocBlock */
77-
[$docBlock] = $this->getDocBlock($class, $property);
78+
[$docBlock] = $this->findDocBlock($class, $property);
7879
if (!$docBlock) {
7980
return null;
8081
}
@@ -101,7 +102,7 @@ public function getShortDescription(string $class, string $property, array $cont
101102
public function getLongDescription(string $class, string $property, array $context = []): ?string
102103
{
103104
/** @var $docBlock DocBlock */
104-
[$docBlock] = $this->getDocBlock($class, $property);
105+
[$docBlock] = $this->findDocBlock($class, $property);
105106
if (!$docBlock) {
106107
return null;
107108
}
@@ -114,7 +115,7 @@ public function getLongDescription(string $class, string $property, array $conte
114115
public function getTypes(string $class, string $property, array $context = []): ?array
115116
{
116117
/** @var $docBlock DocBlock */
117-
[$docBlock, $source, $prefix] = $this->getDocBlock($class, $property);
118+
[$docBlock, $source, $prefix] = $this->findDocBlock($class, $property);
118119
if (!$docBlock) {
119120
return null;
120121
}
@@ -187,6 +188,13 @@ public function getTypesFromConstructor(string $class, string $property): ?array
187188
return array_merge([], ...$types);
188189
}
189190

191+
public function getDocBlock(string $class, string $property): ?DocBlock
192+
{
193+
$output = $this->findDocBlock($class, $property);
194+
195+
return $output[0];
196+
}
197+
190198
private function getDocBlockFromConstructor(string $class, string $property): ?DocBlock
191199
{
192200
try {
@@ -219,7 +227,7 @@ private function filterDocBlockParams(DocBlock $docBlock, string $allowedParam):
219227
/**
220228
* @return array{DocBlock|null, int|null, string|null}
221229
*/
222-
private function getDocBlock(string $class, string $property): array
230+
private function findDocBlock(string $class, string $property): array
223231
{
224232
$propertyHash = sprintf('%s::%s', $class, $property);
225233

‎src/Symfony/Component/PropertyInfo/PropertyDocBlockExtractorInterface.php‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
<?php
2+
3+
/*
4+
* This file is part of the Symfony package.
5+
*
6+
* (c) Fabien Potencier <[email protected]>
7+
*
8+
* For the full copyright and license information, please view the LICENSE
9+
* file that was distributed with this source code.
10+
*/
11+
12+
namespace Symfony\Component\PropertyInfo;
13+
14+
use phpDocumentor\Reflection\DocBlock;
15+
16+
/**
17+
* Extract a property's doc block.
18+
*
19+
* A property's doc block may be located on a constructor promoted argument, on
20+
* the property or on a mutator for that property.
21+
*
22+
* @author Tobias Nyholm <[email protected]>
23+
*/
24+
interface PropertyDocBlockExtractorInterface
25+
{
26+
/**
27+
* Gets the first available doc block for a property. It finds the doc block
28+
* by the following priority:
29+
* - constructor promoted argument
30+
* - the class property
31+
* - a mutator method for that property
32+
*
33+
* If no doc block is found, it will return null.
34+
*/
35+
public function getDocBlock(string $class, string $property): ?DocBlock;
36+
}

‎src/Symfony/Component/PropertyInfo/Tests/Extractor/PhpDocExtractorTest.php‎

Lines changed: 19 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@
1111

1212
namespace Symfony\Component\PropertyInfo\Tests\Extractor;
1313

14+
use phpDocumentor\Reflection\DocBlock;
1415
use PHPUnit\Framework\TestCase;
1516
use Symfony\Component\PropertyInfo\Extractor\PhpDocExtractor;
1617
use Symfony\Component\PropertyInfo\Tests\Fixtures\Dummy;
@@ -38,9 +39,22 @@ protected function setUp(): void
3839
*/
3940
public function testExtract($property, ?array $type, $shortDescription, $longDescription)
4041
{
41-
$this->assertEquals($type, $this->extractor->getTypes('Symfony\Component\PropertyInfo\Tests\Fixtures\Dummy', $property));
42-
$this->assertSame($shortDescription, $this->extractor->getShortDescription('Symfony\Component\PropertyInfo\Tests\Fixtures\Dummy', $property));
43-
$this->assertSame($longDescription, $this->extractor->getLongDescription('Symfony\Component\PropertyInfo\Tests\Fixtures\Dummy', $property));
42+
$this->assertEquals($type, $this->extractor->getTypes(Dummy::class, $property));
43+
$this->assertSame($shortDescription, $this->extractor->getShortDescription(Dummy::class, $property));
44+
$this->assertSame($longDescription, $this->extractor->getLongDescription(Dummy::class, $property));
45+
}
46+
47+
public function testGetDocBlock()
48+
{
49+
$docBlock = $this->extractor->getDocBlock(Dummy::class, 'g');
50+
$this->assertInstanceOf(DocBlock::class, $docBlock);
51+
$this->assertSame('Nullable array.', $docBlock->getSummary());
52+
53+
$docBlock = $this->extractor->getDocBlock(Dummy::class, 'noDocBlock;');
54+
$this->assertNull($docBlock);
55+
56+
$docBlock = $this->extractor->getDocBlock(Dummy::class, 'notAvailable');
57+
$this->assertNull($docBlock);
4458
}
4559

4660
public function testParamTagTypeIsOmitted()
@@ -75,7 +89,7 @@ public function testExtractTypesWithNoPrefixes($property, array $type = null)
7589
{
7690
$noPrefixExtractor = new PhpDocExtractor(null, [], [], []);
7791

78-
$this->assertEquals($type, $noPrefixExtractor->getTypes('Symfony\Component\PropertyInfo\Tests\Fixtures\Dummy', $property));
92+
$this->assertEquals($type, $noPrefixExtractor->getTypes(Dummy::class, $property));
7993
}
8094

8195
public static function typesProvider()
@@ -197,7 +211,7 @@ public function testExtractTypesWithCustomPrefixes($property, array $type = null
197211
{
198212
$customExtractor = new PhpDocExtractor(null, ['add', 'remove'], ['is', 'can']);
199213

200-
$this->assertEquals($type, $customExtractor->getTypes('Symfony\Component\PropertyInfo\Tests\Fixtures\Dummy', $property));
214+
$this->assertEquals($type, $customExtractor->getTypes(Dummy::class, $property));
201215
}
202216

203217
public static function typesWithCustomPrefixesProvider()

‎src/Symfony/Component/PropertyInfo/Tests/Extractor/ReflectionExtractorTest.php‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -66,6 +66,7 @@ public function testGetProperties()
6666
'arrayWithKeys',
6767
'arrayWithKeysAndComplexValue',
6868
'arrayOfMixed',
69+
'noDocBlock',
6970
'listOfStrings',
7071
'parentAnnotation',
7172
'foo',
@@ -130,6 +131,7 @@ public function testGetPropertiesWithCustomPrefixes()
130131
'arrayWithKeys',
131132
'arrayWithKeysAndComplexValue',
132133
'arrayOfMixed',
134+
'noDocBlock',
133135
'listOfStrings',
134136
'parentAnnotation',
135137
'foo',
@@ -183,6 +185,7 @@ public function testGetPropertiesWithNoPrefixes()
183185
'arrayWithKeys',
184186
'arrayWithKeysAndComplexValue',
185187
'arrayOfMixed',
188+
'noDocBlock',
186189
'listOfStrings',
187190
'parentAnnotation',
188191
'foo',

‎src/Symfony/Component/PropertyInfo/Tests/Fixtures/Dummy.php‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -155,6 +155,8 @@ class Dummy extends ParentDummy
155155
*/
156156
public $arrayOfMixed;
157157

158+
public $noDocBlock;
159+
158160
/**
159161
* @var list<string>
160162
*/

0 commit comments

Comments
 (0)