vendor/api-platform/core/src/Metadata/Resource/Factory/PhpDocResourceMetadataCollectionFactory.php line 57

  1. <?php
  3. /*
  4.  * This file is part of the API Platform project.
  5.  *
  6.  * (c) Kévin Dunglas <dunglas@gmail.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. declare(strict_types=1);
  14. namespace ApiPlatform\Metadata\Resource\Factory;
  16. use ApiPlatform\Metadata\Operations;
  17. use ApiPlatform\Metadata\Resource\ResourceMetadataCollection;
  18. use phpDocumentor\Reflection\DocBlockFactory;
  19. use phpDocumentor\Reflection\DocBlockFactoryInterface;
  20. use phpDocumentor\Reflection\Types\ContextFactory;
  21. use PHPStan\PhpDocParser\Ast\PhpDoc\PhpDocNode;
  22. use PHPStan\PhpDocParser\Ast\PhpDoc\PhpDocTextNode;
  23. use PHPStan\PhpDocParser\Lexer\Lexer;
  24. use PHPStan\PhpDocParser\Parser\ConstExprParser;
  25. use PHPStan\PhpDocParser\Parser\PhpDocParser;
  26. use PHPStan\PhpDocParser\Parser\TokenIterator;
  27. use PHPStan\PhpDocParser\Parser\TypeParser;
  29. /**
  30.  * Extracts descriptions from PHPDoc.
  31.  *
  32.  * @author Kévin Dunglas <dunglas@gmail.com>
  33.  */
  34. final class PhpDocResourceMetadataCollectionFactory implements ResourceMetadataCollectionFactoryInterface
  35. {
  36.     private readonly ?DocBlockFactoryInterface $docBlockFactory;
  37.     private readonly ?ContextFactory $contextFactory;
  38.     private readonly ?PhpDocParser $phpDocParser;
  39.     private readonly ?Lexer $lexer;
  41.     /** @var array<string, PhpDocNode> */
  42.     private array $docBlocks = [];
  44.     public function __construct(private readonly ResourceMetadataCollectionFactoryInterface $decorated, ?DocBlockFactoryInterface $docBlockFactory = null)
  45.     {
  46.         $contextFactory = null;
  47.         if ($docBlockFactory instanceof DocBlockFactoryInterface) {
  48.             trigger_deprecation('api-platform/core', '3.1', 'Using a 2nd argument to PhpDocResourceMetadataCollectionFactory is deprecated.');
  49.         }
  50.         if (class_exists(DocBlockFactory::class) && class_exists(ContextFactory::class)) {
  51.             $docBlockFactory = $docBlockFactory ?? DocBlockFactory::createInstance();
  52.             $contextFactory = new ContextFactory();
  53.         }
  54.         $this->docBlockFactory = $docBlockFactory;
  55.         $this->contextFactory = $contextFactory;
  56.         if (class_exists(DocBlockFactory::class) && !class_exists(PhpDocParser::class)) {
  57.             trigger_deprecation('api-platform/core', '3.1', 'Using phpdocumentor/reflection-docblock is deprecated. Require phpstan/phpdoc-parser instead.');
  58.         }
  59.         $phpDocParser = null;
  60.         $lexer = null;
  61.         if (class_exists(PhpDocParser::class)) {
  62.             $phpDocParser = new PhpDocParser(new TypeParser(new ConstExprParser()), new ConstExprParser());
  63.             $lexer = new Lexer();
  64.         }
  65.         $this->phpDocParser = $phpDocParser;
  66.         $this->lexer = $lexer;
  67.     }
  69.     /**
  70.      * {@inheritdoc}
  71.      */
  72.     public function create(string $resourceClass): ResourceMetadataCollection
  73.     {
  74.         $resourceMetadataCollection = $this->decorated->create($resourceClass);
  76.         foreach ($resourceMetadataCollection as $key => $resourceMetadata) {
  77.             if (null !== $resourceMetadata->getDescription()) {
  78.                 continue;
  79.             }
  81.             $description = null;
  83.             // Deprecated path. To remove in API Platform 4.
  84.             if (!$this->phpDocParser instanceof PhpDocParser && $this->docBlockFactory instanceof DocBlockFactoryInterface && $this->contextFactory) {
  85.                 $reflectionClass = new \ReflectionClass($resourceClass);
  87.                 try {
  88.                     $docBlock = $this->docBlockFactory->create($reflectionClass, $this->contextFactory->createFromReflector($reflectionClass));
  89.                     $description = $docBlock->getSummary();
  90.                 } catch (\InvalidArgumentException) {
  91.                     // Ignore empty DocBlocks
  92.                 }
  93.             } else {
  94.                 $description = $this->getShortDescription($resourceClass);
  95.             }
  97.             if (!$description) {
  98.                 return $resourceMetadataCollection;
  99.             }
  101.             $resourceMetadataCollection[$key] = $resourceMetadata->withDescription($description);
  103.             $operations = $resourceMetadata->getOperations() ?? new Operations();
  104.             foreach ($operations as $operationName => $operation) {
  105.                 if (null !== $operation->getDescription()) {
  106.                     continue;
  107.                 }
  109.                 $operations->add($operationName, $operation->withDescription($description));
  110.             }
  112.             $resourceMetadataCollection[$key] = $resourceMetadataCollection[$key]->withOperations($operations);
  114.             if (!$resourceMetadata->getGraphQlOperations()) {
  115.                 continue;
  116.             }
  118.             foreach ($graphQlOperations = $resourceMetadata->getGraphQlOperations() as $operationName => $operation) {
  119.                 if (null !== $operation->getDescription()) {
  120.                     continue;
  121.                 }
  123.                 $graphQlOperations[$operationName] = $operation->withDescription($description);
  124.             }
  126.             $resourceMetadataCollection[$key] = $resourceMetadataCollection[$key]->withGraphQlOperations($graphQlOperations);
  127.         }
  129.         return $resourceMetadataCollection;
  130.     }
  132.     /**
  133.      * Gets the short description of the class.
  134.      */
  135.     private function getShortDescription(string $class): ?string
  136.     {
  137.         if (!$docBlock = $this->getDocBlock($class)) {
  138.             return null;
  139.         }
  141.         foreach ($docBlock->children as $docChild) {
  142.             if ($docChild instanceof PhpDocTextNode && !empty($docChild->text)) {
  143.                 return $docChild->text;
  144.             }
  145.         }
  147.         return null;
  148.     }
  150.     private function getDocBlock(string $class): ?PhpDocNode
  151.     {
  152.         if (isset($this->docBlocks[$class])) {
  153.             return $this->docBlocks[$class];
  154.         }
  156.         try {
  157.             $reflectionClass = new \ReflectionClass($class);
  158.         } catch (\ReflectionException) {
  159.             return null;
  160.         }
  162.         $rawDocNode = $reflectionClass->getDocComment();
  164.         if (!$rawDocNode) {
  165.             return null;
  166.         }
  168.         $tokens = new TokenIterator($this->lexer->tokenize($rawDocNode));
  169.         $phpDocNode = $this->phpDocParser->parse($tokens);
  170.         $tokens->consumeTokenType(Lexer::TOKEN_END);
  172.         return $this->docBlocks[$class] = $phpDocNode;
  173.     }
  174. }