vendor/symfony/property-info/Extractor/PhpStanExtractor.php line 72

  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\Types\ContextFactory;
  15. use PHPStan\PhpDocParser\Ast\PhpDoc\InvalidTagValueNode;
  16. use PHPStan\PhpDocParser\Ast\PhpDoc\ParamTagValueNode;
  17. use PHPStan\PhpDocParser\Ast\PhpDoc\PhpDocNode;
  18. use PHPStan\PhpDocParser\Ast\PhpDoc\PhpDocTagNode;
  19. use PHPStan\PhpDocParser\Lexer\Lexer;
  20. use PHPStan\PhpDocParser\Parser\ConstExprParser;
  21. use PHPStan\PhpDocParser\Parser\PhpDocParser;
  22. use PHPStan\PhpDocParser\Parser\TokenIterator;
  23. use PHPStan\PhpDocParser\Parser\TypeParser;
  24. use Symfony\Component\PropertyInfo\PhpStan\NameScopeFactory;
  25. use Symfony\Component\PropertyInfo\PropertyTypeExtractorInterface;
  26. use Symfony\Component\PropertyInfo\Type;
  27. use Symfony\Component\PropertyInfo\Util\PhpStanTypeHelper;
  29. /**
  30.  * Extracts data using PHPStan parser.
  31.  *
  32.  * @author Baptiste Leduc <baptiste.leduc@gmail.com>
  33.  */
  34. final class PhpStanExtractor implements PropertyTypeExtractorInterface, ConstructorArgumentTypeExtractorInterface
  35. {
  36.     private const PROPERTY = 0;
  37.     private const ACCESSOR = 1;
  38.     private const MUTATOR = 2;
  40.     /** @var PhpDocParser */
  41.     private $phpDocParser;
  43.     /** @var Lexer */
  44.     private $lexer;
  46.     /** @var NameScopeFactory */
  47.     private $nameScopeFactory;
  49.     /** @var array<string, array{PhpDocNode|null, int|null, string|null, string|null}> */
  50.     private $docBlocks = [];
  51.     private $phpStanTypeHelper;
  52.     private $mutatorPrefixes;
  53.     private $accessorPrefixes;
  54.     private $arrayMutatorPrefixes;
  56.     /**
  57.      * @param list<string>|null $mutatorPrefixes
  58.      * @param list<string>|null $accessorPrefixes
  59.      * @param list<string>|null $arrayMutatorPrefixes
  60.      */
  61.     public function __construct(array $mutatorPrefixes = null, array $accessorPrefixes = null, array $arrayMutatorPrefixes = null)
  62.     {
  63.         if (!class_exists(ContextFactory::class)) {
  64.             throw new \LogicException(sprintf('Unable to use the "%s" class as the "phpdocumentor/type-resolver" package is not installed. Try running composer require "phpdocumentor/type-resolver".', __CLASS__));
  65.         }
  67.         if (!class_exists(PhpDocParser::class)) {
  68.             throw new \LogicException(sprintf('Unable to use the "%s" class as the "phpstan/phpdoc-parser" package is not installed. Try running composer require "phpstan/phpdoc-parser".', __CLASS__));
  69.         }
  71.         $this->phpStanTypeHelper = new PhpStanTypeHelper();
  72.         $this->mutatorPrefixes = $mutatorPrefixes ?? ReflectionExtractor::$defaultMutatorPrefixes;
  73.         $this->accessorPrefixes = $accessorPrefixes ?? ReflectionExtractor::$defaultAccessorPrefixes;
  74.         $this->arrayMutatorPrefixes = $arrayMutatorPrefixes ?? ReflectionExtractor::$defaultArrayMutatorPrefixes;
  76.         $this->phpDocParser = new PhpDocParser(new TypeParser(new ConstExprParser()), new ConstExprParser());
  77.         $this->lexer = new Lexer();
  78.         $this->nameScopeFactory = new NameScopeFactory();
  79.     }
  81.     public function getTypes(string $class, string $property, array $context = []): ?array
  82.     {
  83.         /** @var PhpDocNode|null $docNode */
  84.         [$docNode, $source, $prefix, $declaringClass] = $this->getDocBlock($class, $property);
  85.         $nameScope = $this->nameScopeFactory->create($class, $declaringClass);
  86.         if (null === $docNode) {
  87.             return null;
  88.         }
  90.         switch ($source) {
  91.             case self::PROPERTY:
  92.                 $tag = '@var';
  93.                 break;
  95.             case self::ACCESSOR:
  96.                 $tag = '@return';
  97.                 break;
  99.             case self::MUTATOR:
  100.                 $tag = '@param';
  101.                 break;
  102.         }
  104.         $parentClass = null;
  105.         $types = [];
  106.         foreach ($docNode->getTagsByName($tag) as $tagDocNode) {
  107.             if ($tagDocNode->value instanceof InvalidTagValueNode) {
  108.                 continue;
  109.             }
  111.             if (
  112.                 $tagDocNode->value instanceof ParamTagValueNode
  113.                 && null === $prefix
  114.                 && $tagDocNode->value->parameterName !== '$'.$property
  115.             ) {
  116.                 continue;
  117.             }
  119.             foreach ($this->phpStanTypeHelper->getTypes($tagDocNode->value, $nameScope) as $type) {
  120.                 switch ($type->getClassName()) {
  121.                     case 'self':
  122.                     case 'static':
  123.                         $resolvedClass = $class;
  124.                         break;
  126.                     case 'parent':
  127.                         if (false !== $resolvedClass = $parentClass ??= get_parent_class($class)) {
  128.                             break;
  129.                         }
  130.                         // no break
  132.                     default:
  133.                         $types[] = $type;
  134.                         continue 2;
  135.                 }
  137.                 $types[] = new Type(Type::BUILTIN_TYPE_OBJECT, $type->isNullable(), $resolvedClass, $type->isCollection(), $type->getCollectionKeyTypes(), $type->getCollectionValueTypes());
  138.             }
  139.         }
  141.         if (!isset($types[0])) {
  142.             return null;
  143.         }
  145.         if (!\in_array($prefix, $this->arrayMutatorPrefixes, true)) {
  146.             return $types;
  147.         }
  149.         return [new Type(Type::BUILTIN_TYPE_ARRAY, false, null, true, new Type(Type::BUILTIN_TYPE_INT), $types[0])];
  150.     }
  152.     public function getTypesFromConstructor(string $class, string $property): ?array
  153.     {
  154.         if (null === $tagDocNode = $this->getDocBlockFromConstructor($class, $property)) {
  155.             return null;
  156.         }
  158.         $types = [];
  159.         foreach ($this->phpStanTypeHelper->getTypes($tagDocNode, $this->nameScopeFactory->create($class)) as $type) {
  160.             $types[] = $type;
  161.         }
  163.         if (!isset($types[0])) {
  164.             return null;
  165.         }
  167.         return $types;
  168.     }
  170.     private function getDocBlockFromConstructor(string $class, string $property): ?ParamTagValueNode
  171.     {
  172.         try {
  173.             $reflectionClass = new \ReflectionClass($class);
  174.         } catch (\ReflectionException) {
  175.             return null;
  176.         }
  178.         if (null === $reflectionConstructor = $reflectionClass->getConstructor()) {
  179.             return null;
  180.         }
  182.         if (!$rawDocNode = $reflectionConstructor->getDocComment()) {
  183.             return null;
  184.         }
  186.         $tokens = new TokenIterator($this->lexer->tokenize($rawDocNode));
  187.         $phpDocNode = $this->phpDocParser->parse($tokens);
  188.         $tokens->consumeTokenType(Lexer::TOKEN_END);
  190.         return $this->filterDocBlockParams($phpDocNode, $property);
  191.     }
  193.     private function filterDocBlockParams(PhpDocNode $docNode, string $allowedParam): ?ParamTagValueNode
  194.     {
  195.         $tags = array_values(array_filter($docNode->getTagsByName('@param'), function ($tagNode) use ($allowedParam) {
  196.             return $tagNode instanceof PhpDocTagNode && ('$'.$allowedParam) === $tagNode->value->parameterName;
  197.         }));
  199.         if (!$tags) {
  200.             return null;
  201.         }
  203.         return $tags[0]->value;
  204.     }
  206.     /**
  207.      * @return array{PhpDocNode|null, int|null, string|null, string|null}
  208.      */
  209.     private function getDocBlock(string $class, string $property): array
  210.     {
  211.         $propertyHash = $class.'::'.$property;
  213.         if (isset($this->docBlocks[$propertyHash])) {
  214.             return $this->docBlocks[$propertyHash];
  215.         }
  217.         $ucFirstProperty = ucfirst($property);
  219.         if ([$docBlock, $source, $declaringClass] = $this->getDocBlockFromProperty($class, $property)) {
  220.             $data = [$docBlock, $source, null, $declaringClass];
  221.         } elseif ([$docBlock, $_, $declaringClass] = $this->getDocBlockFromMethod($class, $ucFirstProperty, self::ACCESSOR)) {
  222.             $data = [$docBlock, self::ACCESSOR, null, $declaringClass];
  223.         } elseif ([$docBlock, $prefix, $declaringClass] = $this->getDocBlockFromMethod($class, $ucFirstProperty, self::MUTATOR)) {
  224.             $data = [$docBlock, self::MUTATOR, $prefix, $declaringClass];
  225.         } else {
  226.             $data = [null, null, null, null];
  227.         }
  229.         return $this->docBlocks[$propertyHash] = $data;
  230.     }
  232.     /**
  233.      * @return array{PhpDocNode, int, string}|null
  234.      */
  235.     private function getDocBlockFromProperty(string $class, string $property): ?array
  236.     {
  237.         // Use a ReflectionProperty instead of $class to get the parent class if applicable
  238.         try {
  239.             $reflectionProperty = new \ReflectionProperty($class, $property);
  240.         } catch (\ReflectionException) {
  241.             return null;
  242.         }
  244.         $source = self::PROPERTY;
  246.         if ($reflectionProperty->isPromoted()) {
  247.             $constructor = new \ReflectionMethod($class, '__construct');
  248.             $rawDocNode = $constructor->getDocComment();
  249.             $source = self::MUTATOR;
  250.         } else {
  251.             $rawDocNode = $reflectionProperty->getDocComment();
  252.         }
  254.         if (!$rawDocNode) {
  255.             return null;
  256.         }
  258.         $tokens = new TokenIterator($this->lexer->tokenize($rawDocNode));
  259.         $phpDocNode = $this->phpDocParser->parse($tokens);
  260.         $tokens->consumeTokenType(Lexer::TOKEN_END);
  262.         return [$phpDocNode, $source, $reflectionProperty->class];
  263.     }
  265.     /**
  266.      * @return array{PhpDocNode, string, string}|null
  267.      */
  268.     private function getDocBlockFromMethod(string $class, string $ucFirstProperty, int $type): ?array
  269.     {
  270.         $prefixes = self::ACCESSOR === $type ? $this->accessorPrefixes : $this->mutatorPrefixes;
  271.         $prefix = null;
  273.         foreach ($prefixes as $prefix) {
  274.             $methodName = $prefix.$ucFirstProperty;
  276.             try {
  277.                 $reflectionMethod = new \ReflectionMethod($class, $methodName);
  278.                 if ($reflectionMethod->isStatic()) {
  279.                     continue;
  280.                 }
  282.                 if (
  283.                     (self::ACCESSOR === $type && 0 === $reflectionMethod->getNumberOfRequiredParameters())
  284.                     || (self::MUTATOR === $type && $reflectionMethod->getNumberOfParameters() >= 1)
  285.                 ) {
  286.                     break;
  287.                 }
  288.             } catch (\ReflectionException) {
  289.                 // Try the next prefix if the method doesn't exist
  290.             }
  291.         }
  293.         if (!isset($reflectionMethod)) {
  294.             return null;
  295.         }
  297.         if (null === $rawDocNode = $reflectionMethod->getDocComment() ?: null) {
  298.             return null;
  299.         }
  301.         $tokens = new TokenIterator($this->lexer->tokenize($rawDocNode));
  302.         $phpDocNode = $this->phpDocParser->parse($tokens);
  303.         $tokens->consumeTokenType(Lexer::TOKEN_END);
  305.         return [$phpDocNode, $prefix, $reflectionMethod->class];
  306.     }
  307. }