symfony · fabpot · Dec 4, 2023 · Nov 17, 2023
@@ -1,6 +1,11 @@
 CHANGELOG
 =========
 
+7.1
+---
+
+ * Introduce `PropertyDocBlockExtractorInterface` to extract a property's doc block
+
 6.4
 ---
 

@@ -18,6 +18,7 @@
 use phpDocumentor\Reflection\Types\Context;
 use phpDocumentor\Reflection\Types\ContextFactory;
 use Symfony\Component\PropertyInfo\PropertyDescriptionExtractorInterface;
+use Symfony\Component\PropertyInfo\PropertyDocBlockExtractorInterface;
 use Symfony\Component\PropertyInfo\PropertyTypeExtractorInterface;
 use Symfony\Component\PropertyInfo\Type;
 use Symfony\Component\PropertyInfo\Util\PhpDocTypeHelper;
@@ -29,7 +30,7 @@
  *
  * @final
  */
-class PhpDocExtractor implements PropertyDescriptionExtractorInterface, PropertyTypeExtractorInterface, ConstructorArgumentTypeExtractorInterface
+class PhpDocExtractor implements PropertyDescriptionExtractorInterface, PropertyTypeExtractorInterface, ConstructorArgumentTypeExtractorInterface, PropertyDocBlockExtractorInterface
 {
     public const PROPERTY = 0;
     public const ACCESSOR = 1;
@@ -74,7 +75,7 @@ public function __construct(DocBlockFactoryInterface $docBlockFactory = null, ar
     public function getShortDescription(string $class, string $property, array $context = []): ?string
     {
         /** @var $docBlock DocBlock */
-        [$docBlock] = $this->getDocBlock($class, $property);
+        [$docBlock] = $this->findDocBlock($class, $property);
         if (!$docBlock) {
             return null;
         }
@@ -101,7 +102,7 @@ public function getShortDescription(string $class, string $property, array $cont
     public function getLongDescription(string $class, string $property, array $context = []): ?string
     {
         /** @var $docBlock DocBlock */
-        [$docBlock] = $this->getDocBlock($class, $property);
+        [$docBlock] = $this->findDocBlock($class, $property);
         if (!$docBlock) {
             return null;
         }
@@ -114,7 +115,7 @@ public function getLongDescription(string $class, string $property, array $conte
     public function getTypes(string $class, string $property, array $context = []): ?array
     {
         /** @var $docBlock DocBlock */
-        [$docBlock, $source, $prefix] = $this->getDocBlock($class, $property);
+        [$docBlock, $source, $prefix] = $this->findDocBlock($class, $property);
         if (!$docBlock) {
             return null;
         }
@@ -187,6 +188,13 @@ public function getTypesFromConstructor(string $class, string $property): ?array
         return array_merge([], ...$types);
     }
 
+    public function getDocBlock(string $class, string $property): ?DocBlock
+    {
+        $output = $this->findDocBlock($class, $property);
+
+        return $output[0];
+    }
+
     private function getDocBlockFromConstructor(string $class, string $property): ?DocBlock
     {
         try {
@@ -219,7 +227,7 @@ private function filterDocBlockParams(DocBlock $docBlock, string $allowedParam):
     /**
      * @return array{DocBlock|null, int|null, string|null}
      */
-    private function getDocBlock(string $class, string $property): array
+    private function findDocBlock(string $class, string $property): array
     {
         $propertyHash = sprintf('%s::%s', $class, $property);
 

@@ -0,0 +1,36 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\PropertyInfo;
+
+use phpDocumentor\Reflection\DocBlock;
+
+/**
+ * Extract a property's doc block.
+ *
+ * A property's doc block may be located on a constructor promoted argument, on
+ * the property or on a mutator for that property.
+ *
+ * @author Tobias Nyholm <[email protected]>
+ */
+interface PropertyDocBlockExtractorInterface
+{
+    /**
+     * Gets the first available doc block for a property. It finds the doc block
+     * by the following priority:
+     *  - constructor promoted argument
+     *  - the class property
+     *  - a mutator method for that property
+     *
+     * If no doc block is found, it will return null.
+     */
+    public function getDocBlock(string $class, string $property): ?DocBlock;
+}
@@ -11,6 +11,7 @@
 
 namespace Symfony\Component\PropertyInfo\Tests\Extractor;
 
+use phpDocumentor\Reflection\DocBlock;
 use PHPUnit\Framework\TestCase;
 use Symfony\Component\PropertyInfo\Extractor\PhpDocExtractor;
 use Symfony\Component\PropertyInfo\Tests\Fixtures\Dummy;
@@ -38,9 +39,22 @@ protected function setUp(): void
      */
     public function testExtract($property, ?array $type, $shortDescription, $longDescription)
     {
-        $this->assertEquals($type, $this->extractor->getTypes('Symfony\Component\PropertyInfo\Tests\Fixtures\Dummy', $property));
-        $this->assertSame($shortDescription, $this->extractor->getShortDescription('Symfony\Component\PropertyInfo\Tests\Fixtures\Dummy', $property));
-        $this->assertSame($longDescription, $this->extractor->getLongDescription('Symfony\Component\PropertyInfo\Tests\Fixtures\Dummy', $property));
+        $this->assertEquals($type, $this->extractor->getTypes(Dummy::class, $property));
+        $this->assertSame($shortDescription, $this->extractor->getShortDescription(Dummy::class, $property));
+        $this->assertSame($longDescription, $this->extractor->getLongDescription(Dummy::class, $property));
+    }
+
+    public function testGetDocBlock()
+    {
+        $docBlock = $this->extractor->getDocBlock(Dummy::class, 'g');
+        $this->assertInstanceOf(DocBlock::class, $docBlock);
+        $this->assertSame('Nullable array.', $docBlock->getSummary());
+
+        $docBlock = $this->extractor->getDocBlock(Dummy::class, 'noDocBlock;');
+        $this->assertNull($docBlock);
+
+        $docBlock = $this->extractor->getDocBlock(Dummy::class, 'notAvailable');
+        $this->assertNull($docBlock);
     }
 
     public function testParamTagTypeIsOmitted()
@@ -75,7 +89,7 @@ public function testExtractTypesWithNoPrefixes($property, array $type = null)
     {
         $noPrefixExtractor = new PhpDocExtractor(null, [], [], []);
 
-        $this->assertEquals($type, $noPrefixExtractor->getTypes('Symfony\Component\PropertyInfo\Tests\Fixtures\Dummy', $property));
+        $this->assertEquals($type, $noPrefixExtractor->getTypes(Dummy::class, $property));
     }
 
     public static function typesProvider()
@@ -197,7 +211,7 @@ public function testExtractTypesWithCustomPrefixes($property, array $type = null
     {
         $customExtractor = new PhpDocExtractor(null, ['add', 'remove'], ['is', 'can']);
 
-        $this->assertEquals($type, $customExtractor->getTypes('Symfony\Component\PropertyInfo\Tests\Fixtures\Dummy', $property));
+        $this->assertEquals($type, $customExtractor->getTypes(Dummy::class, $property));
     }
 
     public static function typesWithCustomPrefixesProvider()

@@ -66,6 +66,7 @@ public function testGetProperties()
                 'arrayWithKeys',
                 'arrayWithKeysAndComplexValue',
                 'arrayOfMixed',
+                'noDocBlock',
                 'listOfStrings',
                 'parentAnnotation',
                 'foo',
@@ -130,6 +131,7 @@ public function testGetPropertiesWithCustomPrefixes()
                 'arrayWithKeys',
                 'arrayWithKeysAndComplexValue',
                 'arrayOfMixed',
+                'noDocBlock',
                 'listOfStrings',
                 'parentAnnotation',
                 'foo',
@@ -183,6 +185,7 @@ public function testGetPropertiesWithNoPrefixes()
                 'arrayWithKeys',
                 'arrayWithKeysAndComplexValue',
                 'arrayOfMixed',
+                'noDocBlock',
                 'listOfStrings',
                 'parentAnnotation',
                 'foo',

@@ -155,6 +155,8 @@ class Dummy extends ParentDummy
      */
     public $arrayOfMixed;
 
+    public $noDocBlock;
+
     /**
      * @var list<string>
      */
-Original file line number
+Diff line change
@@ Expand Up / @@ -155,6 +155,8 @@ class Dummy extends ParentDummy @@
          */
         public $arrayOfMixed;
+        public $noDocBlock;
         /**
          * @var list<string>
          */
@@ Expand Down @@