vendor/symfony/property-info/Extractor/PhpDocExtractor.php line 68

  1. <?php
  3. /*
  4.  * This file is part of the Symfony package.
  5.  *
  6.  * (c) Fabien Potencier <fabien@symfony.com>
  7.  *
  8.  * For the full copyright and license information, please view the LICENSE
  9.  * file that was distributed with this source code.
  10.  */
  12. namespace Symfony\Component\PropertyInfo\Extractor;
  14. use phpDocumentor\Reflection\DocBlock;
  15. use phpDocumentor\Reflection\DocBlock\Tags\InvalidTag;
  16. use phpDocumentor\Reflection\DocBlockFactory;
  17. use phpDocumentor\Reflection\DocBlockFactoryInterface;
  18. use phpDocumentor\Reflection\Types\Context;
  19. use phpDocumentor\Reflection\Types\ContextFactory;
  20. use Symfony\Component\PropertyInfo\PropertyDescriptionExtractorInterface;
  21. use Symfony\Component\PropertyInfo\PropertyTypeExtractorInterface;
  22. use Symfony\Component\PropertyInfo\Type;
  23. use Symfony\Component\PropertyInfo\Util\PhpDocTypeHelper;
  25. /**
  26.  * Extracts data using a PHPDoc parser.
  27.  *
  28.  * @author Kévin Dunglas <dunglas@gmail.com>
  29.  *
  30.  * @final
  31.  */
  32. class PhpDocExtractor implements PropertyDescriptionExtractorInterface, PropertyTypeExtractorInterface, ConstructorArgumentTypeExtractorInterface
  33. {
  34.     public const PROPERTY = 0;
  35.     public const ACCESSOR = 1;
  36.     public const MUTATOR = 2;
  38.     /**
  39.      * @var array<string, array{DocBlock|null, int|null, string|null}>
  40.      */
  41.     private $docBlocks = [];
  43.     /**
  44.      * @var Context[]
  45.      */
  46.     private $contexts = [];
  48.     private $docBlockFactory;
  49.     private $contextFactory;
  50.     private $phpDocTypeHelper;
  51.     private $mutatorPrefixes;
  52.     private $accessorPrefixes;
  53.     private $arrayMutatorPrefixes;
  55.     /**
  56.      * @param string[]|null $mutatorPrefixes
  57.      * @param string[]|null $accessorPrefixes
  58.      * @param string[]|null $arrayMutatorPrefixes
  59.      */
  60.     public function __construct(DocBlockFactoryInterface $docBlockFactory = null, array $mutatorPrefixes = null, array $accessorPrefixes = null, array $arrayMutatorPrefixes = null)
  61.     {
  62.         if (!class_exists(DocBlockFactory::class)) {
  63.             throw new \LogicException(sprintf('Unable to use the "%s" class as the "phpdocumentor/reflection-docblock" package is not installed. Try running composer require "phpdocumentor/reflection-docblock".', __CLASS__));
  64.         }
  66.         $this->docBlockFactory = $docBlockFactory ?: DocBlockFactory::createInstance();
  67.         $this->contextFactory = new ContextFactory();
  68.         $this->phpDocTypeHelper = new PhpDocTypeHelper();
  69.         $this->mutatorPrefixes = $mutatorPrefixes ?? ReflectionExtractor::$defaultMutatorPrefixes;
  70.         $this->accessorPrefixes = $accessorPrefixes ?? ReflectionExtractor::$defaultAccessorPrefixes;
  71.         $this->arrayMutatorPrefixes = $arrayMutatorPrefixes ?? ReflectionExtractor::$defaultArrayMutatorPrefixes;
  72.     }
  74.     public function getShortDescription(string $class, string $property, array $context = []): ?string
  75.     {
  76.         /** @var $docBlock DocBlock */
  77.         [$docBlock] = $this->getDocBlock($class, $property);
  78.         if (!$docBlock) {
  79.             return null;
  80.         }
  82.         $shortDescription = $docBlock->getSummary();
  84.         if (!empty($shortDescription)) {
  85.             return $shortDescription;
  86.         }
  88.         foreach ($docBlock->getTagsByName('var') as $var) {
  89.             if ($var && !$var instanceof InvalidTag) {
  90.                 $varDescription = $var->getDescription()->render();
  92.                 if (!empty($varDescription)) {
  93.                     return $varDescription;
  94.                 }
  95.             }
  96.         }
  98.         return null;
  99.     }
  101.     public function getLongDescription(string $class, string $property, array $context = []): ?string
  102.     {
  103.         /** @var $docBlock DocBlock */
  104.         [$docBlock] = $this->getDocBlock($class, $property);
  105.         if (!$docBlock) {
  106.             return null;
  107.         }
  109.         $contents = $docBlock->getDescription()->render();
  111.         return '' === $contents ? null : $contents;
  112.     }
  114.     public function getTypes(string $class, string $property, array $context = []): ?array
  115.     {
  116.         /** @var $docBlock DocBlock */
  117.         [$docBlock, $source, $prefix] = $this->getDocBlock($class, $property);
  118.         if (!$docBlock) {
  119.             return null;
  120.         }
  122.         $tag = match ($source) {
  123.             self::PROPERTY => 'var',
  124.             self::ACCESSOR => 'return',
  125.             self::MUTATOR => 'param',
  126.         };
  128.         $parentClass = null;
  129.         $types = [];
  130.         /** @var DocBlock\Tags\Var_|DocBlock\Tags\Return_|DocBlock\Tags\Param $tag */
  131.         foreach ($docBlock->getTagsByName($tag) as $tag) {
  132.             if ($tag && !$tag instanceof InvalidTag && null !== $tag->getType()) {
  133.                 foreach ($this->phpDocTypeHelper->getTypes($tag->getType()) as $type) {
  134.                     switch ($type->getClassName()) {
  135.                         case 'self':
  136.                         case 'static':
  137.                             $resolvedClass = $class;
  138.                             break;
  140.                         case 'parent':
  141.                             if (false !== $resolvedClass = $parentClass ??= get_parent_class($class)) {
  142.                                 break;
  143.                             }
  144.                             // no break
  146.                         default:
  147.                             $types[] = $type;
  148.                             continue 2;
  149.                     }
  151.                     $types[] = new Type(Type::BUILTIN_TYPE_OBJECT, $type->isNullable(), $resolvedClass, $type->isCollection(), $type->getCollectionKeyTypes(), $type->getCollectionValueTypes());
  152.                 }
  153.             }
  154.         }
  156.         if (!isset($types[0])) {
  157.             return null;
  158.         }
  160.         if (!\in_array($prefix, $this->arrayMutatorPrefixes)) {
  161.             return $types;
  162.         }
  164.         return [new Type(Type::BUILTIN_TYPE_ARRAY, false, null, true, new Type(Type::BUILTIN_TYPE_INT), $types[0])];
  165.     }
  167.     public function getTypesFromConstructor(string $class, string $property): ?array
  168.     {
  169.         $docBlock = $this->getDocBlockFromConstructor($class, $property);
  171.         if (!$docBlock) {
  172.             return null;
  173.         }
  175.         $types = [];
  176.         /** @var DocBlock\Tags\Var_|DocBlock\Tags\Return_|DocBlock\Tags\Param $tag */
  177.         foreach ($docBlock->getTagsByName('param') as $tag) {
  178.             if ($tag && null !== $tag->getType()) {
  179.                 $types[] = $this->phpDocTypeHelper->getTypes($tag->getType());
  180.             }
  181.         }
  183.         if (!isset($types[0]) || [] === $types[0]) {
  184.             return null;
  185.         }
  187.         return array_merge([], ...$types);
  188.     }
  190.     private function getDocBlockFromConstructor(string $class, string $property): ?DocBlock
  191.     {
  192.         try {
  193.             $reflectionClass = new \ReflectionClass($class);
  194.         } catch (\ReflectionException) {
  195.             return null;
  196.         }
  197.         $reflectionConstructor = $reflectionClass->getConstructor();
  198.         if (!$reflectionConstructor) {
  199.             return null;
  200.         }
  202.         try {
  203.             $docBlock = $this->docBlockFactory->create($reflectionConstructor, $this->contextFactory->createFromReflector($reflectionConstructor));
  205.             return $this->filterDocBlockParams($docBlock, $property);
  206.         } catch (\InvalidArgumentException) {
  207.             return null;
  208.         }
  209.     }
  211.     private function filterDocBlockParams(DocBlock $docBlock, string $allowedParam): DocBlock
  212.     {
  213.         $tags = array_values(array_filter($docBlock->getTagsByName('param'), function ($tag) use ($allowedParam) {
  214.             return $tag instanceof DocBlock\Tags\Param && $allowedParam === $tag->getVariableName();
  215.         }));
  217.         return new DocBlock($docBlock->getSummary(), $docBlock->getDescription(), $tags, $docBlock->getContext(),
  218.             $docBlock->getLocation(), $docBlock->isTemplateStart(), $docBlock->isTemplateEnd());
  219.     }
  221.     /**
  222.      * @return array{DocBlock|null, int|null, string|null}
  223.      */
  224.     private function getDocBlock(string $class, string $property): array
  225.     {
  226.         $propertyHash = sprintf('%s::%s', $class, $property);
  228.         if (isset($this->docBlocks[$propertyHash])) {
  229.             return $this->docBlocks[$propertyHash];
  230.         }
  232.         try {
  233.             $reflectionProperty = new \ReflectionProperty($class, $property);
  234.         } catch (\ReflectionException) {
  235.             $reflectionProperty = null;
  236.         }
  238.         $ucFirstProperty = ucfirst($property);
  240.         switch (true) {
  241.             case $reflectionProperty?->isPromoted() && $docBlock = $this->getDocBlockFromConstructor($class, $property):
  242.                 $data = [$docBlock, self::MUTATOR, null];
  243.                 break;
  245.             case $docBlock = $this->getDocBlockFromProperty($class, $property):
  246.                 $data = [$docBlock, self::PROPERTY, null];
  247.                 break;
  249.             case [$docBlock] = $this->getDocBlockFromMethod($class, $ucFirstProperty, self::ACCESSOR):
  250.                 $data = [$docBlock, self::ACCESSOR, null];
  251.                 break;
  253.             case [$docBlock, $prefix] = $this->getDocBlockFromMethod($class, $ucFirstProperty, self::MUTATOR):
  254.                 $data = [$docBlock, self::MUTATOR, $prefix];
  255.                 break;
  257.             default:
  258.                 $data = [null, null, null];
  259.         }
  261.         return $this->docBlocks[$propertyHash] = $data;
  262.     }
  264.     private function getDocBlockFromProperty(string $class, string $property): ?DocBlock
  265.     {
  266.         // Use a ReflectionProperty instead of $class to get the parent class if applicable
  267.         try {
  268.             $reflectionProperty = new \ReflectionProperty($class, $property);
  269.         } catch (\ReflectionException) {
  270.             return null;
  271.         }
  273.         $reflector = $reflectionProperty->getDeclaringClass();
  275.         foreach ($reflector->getTraits() as $trait) {
  276.             if ($trait->hasProperty($property)) {
  277.                 return $this->getDocBlockFromProperty($trait->getName(), $property);
  278.             }
  279.         }
  281.         try {
  282.             return $this->docBlockFactory->create($reflectionProperty, $this->createFromReflector($reflector));
  283.         } catch (\InvalidArgumentException|\RuntimeException) {
  284.             return null;
  285.         }
  286.     }
  288.     /**
  289.      * @return array{DocBlock, string}|null
  290.      */
  291.     private function getDocBlockFromMethod(string $class, string $ucFirstProperty, int $type): ?array
  292.     {
  293.         $prefixes = self::ACCESSOR === $type ? $this->accessorPrefixes : $this->mutatorPrefixes;
  294.         $prefix = null;
  296.         foreach ($prefixes as $prefix) {
  297.             $methodName = $prefix.$ucFirstProperty;
  299.             try {
  300.                 $reflectionMethod = new \ReflectionMethod($class, $methodName);
  301.                 if ($reflectionMethod->isStatic()) {
  302.                     continue;
  303.                 }
  305.                 if (
  306.                     (self::ACCESSOR === $type && 0 === $reflectionMethod->getNumberOfRequiredParameters()) ||
  307.                     (self::MUTATOR === $type && $reflectionMethod->getNumberOfParameters() >= 1)
  308.                 ) {
  309.                     break;
  310.                 }
  311.             } catch (\ReflectionException) {
  312.                 // Try the next prefix if the method doesn't exist
  313.             }
  314.         }
  316.         if (!isset($reflectionMethod)) {
  317.             return null;
  318.         }
  320.         $reflector = $reflectionMethod->getDeclaringClass();
  322.         foreach ($reflector->getTraits() as $trait) {
  323.             if ($trait->hasMethod($methodName)) {
  324.                 return $this->getDocBlockFromMethod($trait->getName(), $ucFirstProperty, $type);
  325.             }
  326.         }
  328.         try {
  329.             return [$this->docBlockFactory->create($reflectionMethod, $this->createFromReflector($reflector)), $prefix];
  330.         } catch (\InvalidArgumentException|\RuntimeException) {
  331.             return null;
  332.         }
  333.     }
  335.     /**
  336.      * Prevents a lot of redundant calls to ContextFactory::createForNamespace().
  337.      */
  338.     private function createFromReflector(\ReflectionClass $reflector): Context
  339.     {
  340.         $cacheKey = $reflector->getNamespaceName().':'.$reflector->getFileName();
  342.         if (isset($this->contexts[$cacheKey])) {
  343.             return $this->contexts[$cacheKey];
  344.         }
  346.         $this->contexts[$cacheKey] = $this->contextFactory->createFromReflector($reflector);
  348.         return $this->contexts[$cacheKey];
  349.     }
  350. }