vendor/doctrine/annotations/lib/Doctrine/Common/Annotations/AnnotationReader.php line 154

  1. <?php
  3. namespace Doctrine\Common\Annotations;
  5. use Doctrine\Common\Annotations\Annotation\IgnoreAnnotation;
  6. use Doctrine\Common\Annotations\Annotation\Target;
  7. use ReflectionClass;
  8. use ReflectionFunction;
  9. use ReflectionMethod;
  10. use ReflectionProperty;
  12. use function array_merge;
  13. use function class_exists;
  14. use function extension_loaded;
  15. use function ini_get;
  17. /**
  18.  * A reader for docblock annotations.
  19.  */
  20. class AnnotationReader implements Reader
  21. {
  22.     /**
  23.      * Global map for imports.
  24.      *
  25.      * @var array<string, class-string>
  26.      */
  27.     private static $globalImports = [
  28.         'ignoreannotation' => Annotation\IgnoreAnnotation::class,
  29.     ];
  31.     /**
  32.      * A list with annotations that are not causing exceptions when not resolved to an annotation class.
  33.      *
  34.      * The names are case sensitive.
  35.      *
  36.      * @var array<string, true>
  37.      */
  38.     private static $globalIgnoredNames = ImplicitlyIgnoredAnnotationNames::LIST;
  40.     /**
  41.      * A list with annotations that are not causing exceptions when not resolved to an annotation class.
  42.      *
  43.      * The names are case sensitive.
  44.      *
  45.      * @var array<string, true>
  46.      */
  47.     private static $globalIgnoredNamespaces = [];
  49.     /**
  50.      * Add a new annotation to the globally ignored annotation names with regard to exception handling.
  51.      *
  52.      * @param string $name
  53.      */
  54.     public static function addGlobalIgnoredName($name)
  55.     {
  56.         self::$globalIgnoredNames[$name] = true;
  57.     }
  59.     /**
  60.      * Add a new annotation to the globally ignored annotation namespaces with regard to exception handling.
  61.      *
  62.      * @param string $namespace
  63.      */
  64.     public static function addGlobalIgnoredNamespace($namespace)
  65.     {
  66.         self::$globalIgnoredNamespaces[$namespace] = true;
  67.     }
  69.     /**
  70.      * Annotations parser.
  71.      *
  72.      * @var DocParser
  73.      */
  74.     private $parser;
  76.     /**
  77.      * Annotations parser used to collect parsing metadata.
  78.      *
  79.      * @var DocParser
  80.      */
  81.     private $preParser;
  83.     /**
  84.      * PHP parser used to collect imports.
  85.      *
  86.      * @var PhpParser
  87.      */
  88.     private $phpParser;
  90.     /**
  91.      * In-memory cache mechanism to store imported annotations per class.
  92.      *
  93.      * @psalm-var array<'class'|'function', array<string, array<string, class-string>>>
  94.      */
  95.     private $imports = [];
  97.     /**
  98.      * In-memory cache mechanism to store ignored annotations per class.
  99.      *
  100.      * @psalm-var array<'class'|'function', array<string, array<string, true>>>
  101.      */
  102.     private $ignoredAnnotationNames = [];
  104.     /**
  105.      * Initializes a new AnnotationReader.
  106.      *
  107.      * @throws AnnotationException
  108.      */
  109.     public function __construct(?DocParser $parser = null)
  110.     {
  111.         if (
  112.             extension_loaded('Zend Optimizer+') && (ini_get('zend_optimizerplus.save_comments') === '0' ||
  113.             ini_get('opcache.save_comments') === '0')
  114.         ) {
  115.             throw AnnotationException::optimizerPlusSaveComments();
  116.         }
  118.         if (extension_loaded('Zend OPcache') && ini_get('opcache.save_comments') === 0) {
  119.             throw AnnotationException::optimizerPlusSaveComments();
  120.         }
  122.         // Make sure that the IgnoreAnnotation annotation is loaded
  123.         class_exists(IgnoreAnnotation::class);
  125.         $this->parser = $parser ?: new DocParser();
  127.         $this->preParser = new DocParser();
  129.         $this->preParser->setImports(self::$globalImports);
  130.         $this->preParser->setIgnoreNotImportedAnnotations(true);
  131.         $this->preParser->setIgnoredAnnotationNames(self::$globalIgnoredNames);
  133.         $this->phpParser = new PhpParser();
  134.     }
  136.     /**
  137.      * {@inheritDoc}
  138.      */
  139.     public function getClassAnnotations(ReflectionClass $class)
  140.     {
  141.         $this->parser->setTarget(Target::TARGET_CLASS);
  142.         $this->parser->setImports($this->getImports($class));
  143.         $this->parser->setIgnoredAnnotationNames($this->getIgnoredAnnotationNames($class));
  144.         $this->parser->setIgnoredAnnotationNamespaces(self::$globalIgnoredNamespaces);
  146.         return $this->parser->parse($class->getDocComment(), 'class ' . $class->getName());
  147.     }
  149.     /**
  150.      * {@inheritDoc}
  151.      */
  152.     public function getClassAnnotation(ReflectionClass $class, $annotationName)
  153.     {
  154.         $annotations = $this->getClassAnnotations($class);
  156.         foreach ($annotations as $annotation) {
  157.             if ($annotation instanceof $annotationName) {
  158.                 return $annotation;
  159.             }
  160.         }
  162.         return null;
  163.     }
  165.     /**
  166.      * {@inheritDoc}
  167.      */
  168.     public function getPropertyAnnotations(ReflectionProperty $property)
  169.     {
  170.         $class   = $property->getDeclaringClass();
  171.         $context = 'property ' . $class->getName() . '::$' . $property->getName();
  173.         $this->parser->setTarget(Target::TARGET_PROPERTY);
  174.         $this->parser->setImports($this->getPropertyImports($property));
  175.         $this->parser->setIgnoredAnnotationNames($this->getIgnoredAnnotationNames($class));
  176.         $this->parser->setIgnoredAnnotationNamespaces(self::$globalIgnoredNamespaces);
  178.         return $this->parser->parse($property->getDocComment(), $context);
  179.     }
  181.     /**
  182.      * {@inheritDoc}
  183.      */
  184.     public function getPropertyAnnotation(ReflectionProperty $property, $annotationName)
  185.     {
  186.         $annotations = $this->getPropertyAnnotations($property);
  188.         foreach ($annotations as $annotation) {
  189.             if ($annotation instanceof $annotationName) {
  190.                 return $annotation;
  191.             }
  192.         }
  194.         return null;
  195.     }
  197.     /**
  198.      * {@inheritDoc}
  199.      */
  200.     public function getMethodAnnotations(ReflectionMethod $method)
  201.     {
  202.         $class   = $method->getDeclaringClass();
  203.         $context = 'method ' . $class->getName() . '::' . $method->getName() . '()';
  205.         $this->parser->setTarget(Target::TARGET_METHOD);
  206.         $this->parser->setImports($this->getMethodImports($method));
  207.         $this->parser->setIgnoredAnnotationNames($this->getIgnoredAnnotationNames($class));
  208.         $this->parser->setIgnoredAnnotationNamespaces(self::$globalIgnoredNamespaces);
  210.         return $this->parser->parse($method->getDocComment(), $context);
  211.     }
  213.     /**
  214.      * {@inheritDoc}
  215.      */
  216.     public function getMethodAnnotation(ReflectionMethod $method, $annotationName)
  217.     {
  218.         $annotations = $this->getMethodAnnotations($method);
  220.         foreach ($annotations as $annotation) {
  221.             if ($annotation instanceof $annotationName) {
  222.                 return $annotation;
  223.             }
  224.         }
  226.         return null;
  227.     }
  229.     /**
  230.      * Gets the annotations applied to a function.
  231.      *
  232.      * @phpstan-return list<object> An array of Annotations.
  233.      */
  234.     public function getFunctionAnnotations(ReflectionFunction $function): array
  235.     {
  236.         $context = 'function ' . $function->getName();
  238.         $this->parser->setTarget(Target::TARGET_FUNCTION);
  239.         $this->parser->setImports($this->getImports($function));
  240.         $this->parser->setIgnoredAnnotationNames($this->getIgnoredAnnotationNames($function));
  241.         $this->parser->setIgnoredAnnotationNamespaces(self::$globalIgnoredNamespaces);
  243.         return $this->parser->parse($function->getDocComment(), $context);
  244.     }
  246.     /**
  247.      * Gets a function annotation.
  248.      *
  249.      * @return object|null The Annotation or NULL, if the requested annotation does not exist.
  250.      */
  251.     public function getFunctionAnnotation(ReflectionFunction $function, string $annotationName)
  252.     {
  253.         $annotations = $this->getFunctionAnnotations($function);
  255.         foreach ($annotations as $annotation) {
  256.             if ($annotation instanceof $annotationName) {
  257.                 return $annotation;
  258.             }
  259.         }
  261.         return null;
  262.     }
  264.     /**
  265.      * Returns the ignored annotations for the given class or function.
  266.      *
  267.      * @param ReflectionClass|ReflectionFunction $reflection
  268.      *
  269.      * @return array<string, true>
  270.      */
  271.     private function getIgnoredAnnotationNames($reflection): array
  272.     {
  273.         $type = $reflection instanceof ReflectionClass ? 'class' : 'function';
  274.         $name = $reflection->getName();
  276.         if (isset($this->ignoredAnnotationNames[$type][$name])) {
  277.             return $this->ignoredAnnotationNames[$type][$name];
  278.         }
  280.         $this->collectParsingMetadata($reflection);
  282.         return $this->ignoredAnnotationNames[$type][$name];
  283.     }
  285.     /**
  286.      * Retrieves imports for a class or a function.
  287.      *
  288.      * @param ReflectionClass|ReflectionFunction $reflection
  289.      *
  290.      * @return array<string, class-string>
  291.      */
  292.     private function getImports($reflection): array
  293.     {
  294.         $type = $reflection instanceof ReflectionClass ? 'class' : 'function';
  295.         $name = $reflection->getName();
  297.         if (isset($this->imports[$type][$name])) {
  298.             return $this->imports[$type][$name];
  299.         }
  301.         $this->collectParsingMetadata($reflection);
  303.         return $this->imports[$type][$name];
  304.     }
  306.     /**
  307.      * Retrieves imports for methods.
  308.      *
  309.      * @return array<string, class-string>
  310.      */
  311.     private function getMethodImports(ReflectionMethod $method)
  312.     {
  313.         $class        = $method->getDeclaringClass();
  314.         $classImports = $this->getImports($class);
  316.         $traitImports = [];
  318.         foreach ($class->getTraits() as $trait) {
  319.             if (
  320.                 ! $trait->hasMethod($method->getName())
  321.                 || $trait->getFileName() !== $method->getFileName()
  322.             ) {
  323.                 continue;
  324.             }
  326.             $traitImports = array_merge($traitImports, $this->phpParser->parseUseStatements($trait));
  327.         }
  329.         return array_merge($classImports, $traitImports);
  330.     }
  332.     /**
  333.      * Retrieves imports for properties.
  334.      *
  335.      * @return array<string, class-string>
  336.      */
  337.     private function getPropertyImports(ReflectionProperty $property)
  338.     {
  339.         $class        = $property->getDeclaringClass();
  340.         $classImports = $this->getImports($class);
  342.         $traitImports = [];
  344.         foreach ($class->getTraits() as $trait) {
  345.             if (! $trait->hasProperty($property->getName())) {
  346.                 continue;
  347.             }
  349.             $traitImports = array_merge($traitImports, $this->phpParser->parseUseStatements($trait));
  350.         }
  352.         return array_merge($classImports, $traitImports);
  353.     }
  355.     /**
  356.      * Collects parsing metadata for a given class or function.
  357.      *
  358.      * @param ReflectionClass|ReflectionFunction $reflection
  359.      */
  360.     private function collectParsingMetadata($reflection): void
  361.     {
  362.         $type = $reflection instanceof ReflectionClass ? 'class' : 'function';
  363.         $name = $reflection->getName();
  365.         $ignoredAnnotationNames = self::$globalIgnoredNames;
  366.         $annotations            = $this->preParser->parse($reflection->getDocComment(), $type . ' ' . $name);
  368.         foreach ($annotations as $annotation) {
  369.             if (! ($annotation instanceof IgnoreAnnotation)) {
  370.                 continue;
  371.             }
  373.             foreach ($annotation->names as $annot) {
  374.                 $ignoredAnnotationNames[$annot] = true;
  375.             }
  376.         }
  378.         $this->imports[$type][$name] = array_merge(
  379.             self::$globalImports,
  380.             $this->phpParser->parseUseStatements($reflection),
  381.             [
  382.                 '__NAMESPACE__' => $reflection->getNamespaceName(),
  383.                 'self' => $name,
  384.             ]
  385.         );
  387.         $this->ignoredAnnotationNames[$type][$name] = $ignoredAnnotationNames;
  388.     }
  389. }