1. <?php
3. namespace Doctrine\Common\Annotations;
5. use Doctrine\Common\Annotations\Annotation\Attribute;
6. use Doctrine\Common\Annotations\Annotation\Attributes;
7. use Doctrine\Common\Annotations\Annotation\Enum;
8. use Doctrine\Common\Annotations\Annotation\NamedArgumentConstructor;
9. use Doctrine\Common\Annotations\Annotation\Target;
10. use ReflectionClass;
11. use ReflectionException;
12. use ReflectionProperty;
13. use RuntimeException;
14. use stdClass;
15. use Throwable;
17. use function array_keys;
18. use function array_map;
19. use function array_pop;
20. use function array_values;
21. use function class_exists;
22. use function constant;
23. use function count;
24. use function defined;
25. use function explode;
26. use function gettype;
27. use function implode;
28. use function in_array;
29. use function interface_exists;
30. use function is_array;
31. use function is_object;
32. use function json_encode;
33. use function ltrim;
34. use function preg_match;
35. use function reset;
36. use function rtrim;
37. use function sprintf;
38. use function stripos;
39. use function strlen;
40. use function strpos;
41. use function strrpos;
42. use function strtolower;
43. use function substr;
44. use function trim;
46. use const PHP_VERSION_ID;
48. /**
49.  * A parser for docblock annotations.
50.  *
51.  * It is strongly discouraged to change the default annotation parsing process.
52.  */
53. final class DocParser
54. {
55.     /**
56.      * An array of all valid tokens for a class name.
57.      *
58.      * @phpstan-var list<int>
59.      */
60.     private static $classIdentifiers = [
61.         DocLexer::T_IDENTIFIER,
62.         DocLexer::T_TRUE,
63.         DocLexer::T_FALSE,
64.         DocLexer::T_NULL,
65.     ];
67.     /**
68.      * The lexer.
69.      *
70.      * @var DocLexer
71.      */
72.     private $lexer;
74.     /**
75.      * Current target context.
76.      *
77.      * @var int
78.      */
79.     private $target;
81.     /**
82.      * Doc parser used to collect annotation target.
83.      *
84.      * @var DocParser
85.      */
86.     private static $metadataParser;
88.     /**
89.      * Flag to control if the current annotation is nested or not.
90.      *
91.      * @var bool
92.      */
93.     private $isNestedAnnotation = false;
95.     /**
96.      * Hashmap containing all use-statements that are to be used when parsing
97.      * the given doc block.
98.      *
99.      * @var array<string, class-string>
100.      */
101.     private $imports = [];
103.     /**
104.      * This hashmap is used internally to cache results of class_exists()
105.      * look-ups.
106.      *
107.      * @var array<class-string, bool>
108.      */
109.     private $classExists = [];
111.     /**
112.      * Whether annotations that have not been imported should be ignored.
113.      *
114.      * @var bool
115.      */
116.     private $ignoreNotImportedAnnotations = false;
118.     /**
119.      * An array of default namespaces if operating in simple mode.
120.      *
121.      * @var string[]
122.      */
123.     private $namespaces = [];
125.     /**
126.      * A list with annotations that are not causing exceptions when not resolved to an annotation class.
127.      *
128.      * The names must be the raw names as used in the class, not the fully qualified
129.      *
130.      * @var bool[] indexed by annotation name
131.      */
132.     private $ignoredAnnotationNames = [];
134.     /**
135.      * A list with annotations in namespaced format
136.      * that are not causing exceptions when not resolved to an annotation class.
137.      *
138.      * @var bool[] indexed by namespace name
139.      */
140.     private $ignoredAnnotationNamespaces = [];
142.     /** @var string */
143.     private $context = '';
145.     /**
146.      * Hash-map for caching annotation metadata.
147.      *
148.      * @var array<class-string, mixed[]>
149.      */
150.     private static $annotationMetadata = [
151.         Annotation\Target::class => [
152.             'is_annotation'                  => true,
153.             'has_constructor'                => true,
154.             'has_named_argument_constructor' => false,
155.             'properties'                     => [],
156.             'targets_literal'                => 'ANNOTATION_CLASS',
157.             'targets'                        => Target::TARGET_CLASS,
158.             'default_property'               => 'value',
159.             'attribute_types'                => [
160.                 'value'  => [
161.                     'required'   => false,
162.                     'type'       => 'array',
163.                     'array_type' => 'string',
164.                     'value'      => 'array<string>',
165.                 ],
166.             ],
167.         ],
168.         Annotation\Attribute::class => [
169.             'is_annotation'                  => true,
170.             'has_constructor'                => false,
171.             'has_named_argument_constructor' => false,
172.             'targets_literal'                => 'ANNOTATION_ANNOTATION',
173.             'targets'                        => Target::TARGET_ANNOTATION,
174.             'default_property'               => 'name',
175.             'properties'                     => [
176.                 'name'      => 'name',
177.                 'type'      => 'type',
178.                 'required'  => 'required',
179.             ],
180.             'attribute_types'                => [
181.                 'value'  => [
182.                     'required'  => true,
183.                     'type'      => 'string',
184.                     'value'     => 'string',
185.                 ],
186.                 'type'  => [
187.                     'required'  => true,
188.                     'type'      => 'string',
189.                     'value'     => 'string',
190.                 ],
191.                 'required'  => [
192.                     'required'  => false,
193.                     'type'      => 'boolean',
194.                     'value'     => 'boolean',
195.                 ],
196.             ],
197.         ],
198.         Annotation\Attributes::class => [
199.             'is_annotation'                  => true,
200.             'has_constructor'                => false,
201.             'has_named_argument_constructor' => false,
202.             'targets_literal'                => 'ANNOTATION_CLASS',
203.             'targets'                        => Target::TARGET_CLASS,
204.             'default_property'               => 'value',
205.             'properties'                     => ['value' => 'value'],
206.             'attribute_types'                => [
207.                 'value' => [
208.                     'type'      => 'array',
209.                     'required'  => true,
210.                     'array_type' => Annotation\Attribute::class,
211.                     'value'     => 'array<' . Annotation\Attribute::class . '>',
212.                 ],
213.             ],
214.         ],
215.         Annotation\Enum::class => [
216.             'is_annotation'                  => true,
217.             'has_constructor'                => true,
218.             'has_named_argument_constructor' => false,
219.             'targets_literal'                => 'ANNOTATION_PROPERTY',
220.             'targets'                        => Target::TARGET_PROPERTY,
221.             'default_property'               => 'value',
222.             'properties'                     => ['value' => 'value'],
223.             'attribute_types'                => [
224.                 'value' => [
225.                     'type'      => 'array',
226.                     'required'  => true,
227.                 ],
228.                 'literal' => [
229.                     'type'      => 'array',
230.                     'required'  => false,
231.                 ],
232.             ],
233.         ],
234.         Annotation\NamedArgumentConstructor::class => [
235.             'is_annotation'                  => true,
236.             'has_constructor'                => false,
237.             'has_named_argument_constructor' => false,
238.             'targets_literal'                => 'ANNOTATION_CLASS',
239.             'targets'                        => Target::TARGET_CLASS,
240.             'default_property'               => null,
241.             'properties'                     => [],
242.             'attribute_types'                => [],
243.         ],
244.     ];
246.     /**
247.      * Hash-map for handle types declaration.
248.      *
249.      * @var array<string, string>
250.      */
251.     private static $typeMap = [
252.         'float'     => 'double',
253.         'bool'      => 'boolean',
254.         // allow uppercase Boolean in honor of George Boole
255.         'Boolean'   => 'boolean',
256.         'int'       => 'integer',
257.     ];
259.     /**
260.      * Constructs a new DocParser.
261.      */
262.     public function __construct()
263.     {
264.         $this->lexer = new DocLexer();
265.     }
267.     /**
268.      * Sets the annotation names that are ignored during the parsing process.
269.      *
270.      * The names are supposed to be the raw names as used in the class, not the
271.      * fully qualified class names.
272.      *
273.      * @param bool[] $names indexed by annotation name
274.      *
275.      * @return void
276.      */
277.     public function setIgnoredAnnotationNames(array $names)
278.     {
279.         $this->ignoredAnnotationNames = $names;
280.     }
282.     /**
283.      * Sets the annotation namespaces that are ignored during the parsing process.
284.      *
285.      * @param bool[] $ignoredAnnotationNamespaces indexed by annotation namespace name
286.      *
287.      * @return void
288.      */
289.     public function setIgnoredAnnotationNamespaces($ignoredAnnotationNamespaces)
290.     {
291.         $this->ignoredAnnotationNamespaces = $ignoredAnnotationNamespaces;
292.     }
294.     /**
295.      * Sets ignore on not-imported annotations.
296.      *
297.      * @param bool $bool
298.      *
299.      * @return void
300.      */
301.     public function setIgnoreNotImportedAnnotations($bool)
302.     {
303.         $this->ignoreNotImportedAnnotations = (bool) $bool;
304.     }
306.     /**
307.      * Sets the default namespaces.
308.      *
309.      * @param string $namespace
310.      *
311.      * @return void
312.      *
313.      * @throws RuntimeException
314.      */
315.     public function addNamespace($namespace)
316.     {
317.         if ($this->imports) {
318.             throw new RuntimeException('You must either use addNamespace(), or setImports(), but not both.');
319.         }
321.         $this->namespaces[] = $namespace;
322.     }
324.     /**
325.      * Sets the imports.
326.      *
327.      * @param array<string, class-string> $imports
328.      *
329.      * @return void
330.      *
331.      * @throws RuntimeException
332.      */
333.     public function setImports(array $imports)
334.     {
335.         if ($this->namespaces) {
336.             throw new RuntimeException('You must either use addNamespace(), or setImports(), but not both.');
337.         }
339.         $this->imports = $imports;
340.     }
342.     /**
343.      * Sets current target context as bitmask.
344.      *
345.      * @param int $target
346.      *
347.      * @return void
348.      */
349.     public function setTarget($target)
350.     {
351.         $this->target = $target;
352.     }
354.     /**
355.      * Parses the given docblock string for annotations.
356.      *
357.      * @param string $input   The docblock string to parse.
358.      * @param string $context The parsing context.
359.      *
360.      * @phpstan-return list<object> Array of annotations. If no annotations are found, an empty array is returned.
361.      *
362.      * @throws AnnotationException
363.      * @throws ReflectionException
364.      */
365.     public function parse($input, $context = '')
366.     {
367.         $pos = $this->findInitialTokenPosition($input);
368.         if ($pos === null) {
369.             return [];
370.         }
372.         $this->context = $context;
374.         $this->lexer->setInput(trim(substr($input, $pos), '* /'));
375.         $this->lexer->moveNext();
377.         return $this->Annotations();
378.     }
380.     /**
381.      * Finds the first valid annotation
382.      *
383.      * @param string $input The docblock string to parse
384.      */
385.     private function findInitialTokenPosition($input): ?int
386.     {
387.         $pos = 0;
389.         // search for first valid annotation
390.         while (($pos = strpos($input, '@', $pos)) !== false) {
391.             $preceding = substr($input, $pos - 1, 1);
393.             // if the @ is preceded by a space, a tab or * it is valid
394.             if ($pos === 0 || $preceding === ' ' || $preceding === '*' || $preceding === "\t") {
395.                 return $pos;
396.             }
398.             $pos++;
399.         }
401.         return null;
402.     }
404.     /**
405.      * Attempts to match the given token with the current lookahead token.
406.      * If they match, updates the lookahead token; otherwise raises a syntax error.
407.      *
408.      * @param int $token Type of token.
409.      *
410.      * @return bool True if tokens match; false otherwise.
411.      *
412.      * @throws AnnotationException
413.      */
414.     private function match(int $token): bool
415.     {
416.         if (! $this->lexer->isNextToken($token)) {
417.             throw $this->syntaxError($this->lexer->getLiteral($token));
418.         }
420.         return $this->lexer->moveNext();
421.     }
423.     /**
424.      * Attempts to match the current lookahead token with any of the given tokens.
425.      *
426.      * If any of them matches, this method updates the lookahead token; otherwise
427.      * a syntax error is raised.
428.      *
429.      * @phpstan-param list<mixed[]> $tokens
430.      *
431.      * @throws AnnotationException
432.      */
433.     private function matchAny(array $tokens): bool
434.     {
435.         if (! $this->lexer->isNextTokenAny($tokens)) {
436.             throw $this->syntaxError(implode(' or ', array_map([$this->lexer, 'getLiteral'], $tokens)));
437.         }
439.         return $this->lexer->moveNext();
440.     }
442.     /**
443.      * Generates a new syntax error.
444.      *
445.      * @param string       $expected Expected string.
446.      * @param mixed[]|null $token    Optional token.
447.      */
448.     private function syntaxError(string $expected, ?array $token = null): AnnotationException
449.     {
450.         if ($token === null) {
451.             $token = $this->lexer->lookahead;
452.         }
454.         $message  = sprintf('Expected %s, got ', $expected);
455.         $message .= $this->lexer->lookahead === null
456.             ? 'end of string'
457.             : sprintf("'%s' at position %s", $token['value'], $token['position']);
459.         if (strlen($this->context)) {
460.             $message .= ' in ' . $this->context;
461.         }
463.         $message .= '.';
465.         return AnnotationException::syntaxError($message);
466.     }
468.     /**
469.      * Attempts to check if a class exists or not. This never goes through the PHP autoloading mechanism
470.      * but uses the {@link AnnotationRegistry} to load classes.
471.      *
472.      * @param class-string $fqcn
473.      */
474.     private function classExists(string $fqcn): bool
475.     {
476.         if (isset($this->classExists[$fqcn])) {
477.             return $this->classExists[$fqcn];
478.         }
480.         // first check if the class already exists, maybe loaded through another AnnotationReader
481.         if (class_exists($fqcn, false)) {
482.             return $this->classExists[$fqcn] = true;
483.         }
485.         // final check, does this class exist?
486.         return $this->classExists[$fqcn] = AnnotationRegistry::loadAnnotationClass($fqcn);
487.     }
489.     /**
490.      * Collects parsing metadata for a given annotation class
491.      *
492.      * @param class-string $name The annotation name
493.      *
494.      * @throws AnnotationException
495.      * @throws ReflectionException
496.      */
497.     private function collectAnnotationMetadata(string $name): void
498.     {
499.         if (self::$metadataParser === null) {
500.             self::$metadataParser = new self();
502.             self::$metadataParser->setIgnoreNotImportedAnnotations(true);
503.             self::$metadataParser->setIgnoredAnnotationNames($this->ignoredAnnotationNames);
504.             self::$metadataParser->setImports([
505.                 'enum'                     => Enum::class,
506.                 'target'                   => Target::class,
507.                 'attribute'                => Attribute::class,
508.                 'attributes'               => Attributes::class,
509.                 'namedargumentconstructor' => NamedArgumentConstructor::class,
510.             ]);
512.             // Make sure that annotations from metadata are loaded
513.             class_exists(Enum::class);
514.             class_exists(Target::class);
515.             class_exists(Attribute::class);
516.             class_exists(Attributes::class);
517.             class_exists(NamedArgumentConstructor::class);
518.         }
520.         $class      = new ReflectionClass($name);
521.         $docComment = $class->getDocComment();
523.         // Sets default values for annotation metadata
524.         $constructor = $class->getConstructor();
525.         $metadata    = [
526.             'default_property' => null,
527.             'has_constructor'  => $constructor !== null && $constructor->getNumberOfParameters() > 0,
528.             'constructor_args' => [],
529.             'properties'       => [],
530.             'property_types'   => [],
531.             'attribute_types'  => [],
532.             'targets_literal'  => null,
533.             'targets'          => Target::TARGET_ALL,
534.             'is_annotation'    => strpos($docComment, '@Annotation') !== false,
535.         ];
537.         $metadata['has_named_argument_constructor'] = $metadata['has_constructor']
538.             && $class->implementsInterface(NamedArgumentConstructorAnnotation::class);
540.         // verify that the class is really meant to be an annotation
541.         if ($metadata['is_annotation']) {
542.             self::$metadataParser->setTarget(Target::TARGET_CLASS);
544.             foreach (self::$metadataParser->parse($docComment, 'class @' . $name) as $annotation) {
545.                 if ($annotation instanceof Target) {
546.                     $metadata['targets']         = $annotation->targets;
547.                     $metadata['targets_literal'] = $annotation->literal;
549.                     continue;
550.                 }
552.                 if ($annotation instanceof NamedArgumentConstructor) {
553.                     $metadata['has_named_argument_constructor'] = $metadata['has_constructor'];
554.                     if ($metadata['has_named_argument_constructor']) {
555.                         // choose the first argument as the default property
556.                         $metadata['default_property'] = $constructor->getParameters()[0]->getName();
557.                     }
558.                 }
560.                 if (! ($annotation instanceof Attributes)) {
561.                     continue;
562.                 }
564.                 foreach ($annotation->value as $attribute) {
565.                     $this->collectAttributeTypeMetadata($metadata, $attribute);
566.                 }
567.             }
569.             // if not has a constructor will inject values into public properties
570.             if ($metadata['has_constructor'] === false) {
571.                 // collect all public properties
572.                 foreach ($class->getProperties(ReflectionProperty::IS_PUBLIC) as $property) {
573.                     $metadata['properties'][$property->name] = $property->name;
575.                     $propertyComment = $property->getDocComment();
576.                     if ($propertyComment === false) {
577.                         continue;
578.                     }
580.                     $attribute = new Attribute();
582.                     $attribute->required = (strpos($propertyComment, '@Required') !== false);
583.                     $attribute->name     = $property->name;
584.                     $attribute->type     = (strpos($propertyComment, '@var') !== false &&
585.                         preg_match('/@var\s+([^\s]+)/', $propertyComment, $matches))
586.                         ? $matches[1]
587.                         : 'mixed';
589.                     $this->collectAttributeTypeMetadata($metadata, $attribute);
591.                     // checks if the property has @Enum
592.                     if (strpos($propertyComment, '@Enum') === false) {
593.                         continue;
594.                     }
596.                     $context = 'property ' . $class->name . '::$' . $property->name;
598.                     self::$metadataParser->setTarget(Target::TARGET_PROPERTY);
600.                     foreach (self::$metadataParser->parse($propertyComment, $context) as $annotation) {
601.                         if (! $annotation instanceof Enum) {
602.                             continue;
603.                         }
605.                         $metadata['enum'][$property->name]['value']   = $annotation->value;
606.                         $metadata['enum'][$property->name]['literal'] = (! empty($annotation->literal))
607.                             ? $annotation->literal
608.                             : $annotation->value;
609.                     }
610.                 }
612.                 // choose the first property as default property
613.                 $metadata['default_property'] = reset($metadata['properties']);
614.             } elseif ($metadata['has_named_argument_constructor']) {
615.                 foreach ($constructor->getParameters() as $parameter) {
616.                     if ($parameter->isVariadic()) {
617.                         break;
618.                     }
620.                     $metadata['constructor_args'][$parameter->getName()] = [
621.                         'position' => $parameter->getPosition(),
622.                         'default' => $parameter->isOptional() ? $parameter->getDefaultValue() : null,
623.                     ];
624.                 }
625.             }
626.         }
628.         self::$annotationMetadata[$name] = $metadata;
629.     }
631.     /**
632.      * Collects parsing metadata for a given attribute.
633.      *
634.      * @param mixed[] $metadata
635.      */
636.     private function collectAttributeTypeMetadata(array &$metadata, Attribute $attribute): void
637.     {
638.         // handle internal type declaration
639.         $type = self::$typeMap[$attribute->type] ?? $attribute->type;
641.         // handle the case if the property type is mixed
642.         if ($type === 'mixed') {
643.             return;
644.         }
646.         // Evaluate type
647.         $pos = strpos($type, '<');
648.         if ($pos !== false) {
649.             // Checks if the property has array<type>
650.             $arrayType = substr($type, $pos + 1, -1);
651.             $type      = 'array';
653.             if (isset(self::$typeMap[$arrayType])) {
654.                 $arrayType = self::$typeMap[$arrayType];
655.             }
657.             $metadata['attribute_types'][$attribute->name]['array_type'] = $arrayType;
658.         } else {
659.             // Checks if the property has type[]
660.             $pos = strrpos($type, '[');
661.             if ($pos !== false) {
662.                 $arrayType = substr($type, 0, $pos);
663.                 $type      = 'array';
665.                 if (isset(self::$typeMap[$arrayType])) {
666.                     $arrayType = self::$typeMap[$arrayType];
667.                 }
669.                 $metadata['attribute_types'][$attribute->name]['array_type'] = $arrayType;
670.             }
671.         }
673.         $metadata['attribute_types'][$attribute->name]['type']     = $type;
674.         $metadata['attribute_types'][$attribute->name]['value']    = $attribute->type;
675.         $metadata['attribute_types'][$attribute->name]['required'] = $attribute->required;
676.     }
678.     /**
679.      * Annotations ::= Annotation {[ "*" ]* [Annotation]}*
680.      *
681.      * @phpstan-return list<object>
682.      *
683.      * @throws AnnotationException
684.      * @throws ReflectionException
685.      */
686.     private function Annotations(): array
687.     {
688.         $annotations = [];
690.         while ($this->lexer->lookahead !== null) {
691.             if ($this->lexer->lookahead['type'] !== DocLexer::T_AT) {
692.                 $this->lexer->moveNext();
693.                 continue;
694.             }
696.             // make sure the @ is preceded by non-catchable pattern
697.             if (
698.                 $this->lexer->token !== null &&
699.                 $this->lexer->lookahead['position'] === $this->lexer->token['position'] + strlen(
700.                     $this->lexer->token['value']
701.                 )
702.             ) {
703.                 $this->lexer->moveNext();
704.                 continue;
705.             }
707.             // make sure the @ is followed by either a namespace separator, or
708.             // an identifier token
709.             $peek = $this->lexer->glimpse();
710.             if (
711.                 ($peek === null)
712.                 || ($peek['type'] !== DocLexer::T_NAMESPACE_SEPARATOR && ! in_array(
713.                     $peek['type'],
714.                     self::$classIdentifiers,
715.                     true
716.                 ))
717.                 || $peek['position'] !== $this->lexer->lookahead['position'] + 1
718.             ) {
719.                 $this->lexer->moveNext();
720.                 continue;
721.             }
723.             $this->isNestedAnnotation = false;
724.             $annot                    = $this->Annotation();
725.             if ($annot === false) {
726.                 continue;
727.             }
729.             $annotations[] = $annot;
730.         }
732.         return $annotations;
733.     }
735.     /**
736.      * Annotation     ::= "@" AnnotationName MethodCall
737.      * AnnotationName ::= QualifiedName | SimpleName
738.      * QualifiedName  ::= NameSpacePart "\" {NameSpacePart "\"}* SimpleName
739.      * NameSpacePart  ::= identifier | null | false | true
740.      * SimpleName     ::= identifier | null | false | true
741.      *
742.      * @return object|false False if it is not a valid annotation.
743.      *
744.      * @throws AnnotationException
745.      * @throws ReflectionException
746.      */
747.     private function Annotation()
748.     {
749.         $this->match(DocLexer::T_AT);
751.         // check if we have an annotation
752.         $name = $this->Identifier();
754.         if (
755.             $this->lexer->isNextToken(DocLexer::T_MINUS)
756.             && $this->lexer->nextTokenIsAdjacent()
757.         ) {
758.             // Annotations with dashes, such as "@foo-" or "@foo-bar", are to be discarded
759.             return false;
760.         }
762.         // only process names which are not fully qualified, yet
763.         // fully qualified names must start with a \
764.         $originalName = $name;
766.         if ($name[0] !== '\\') {
767.             $pos          = strpos($name, '\\');
768.             $alias        = ($pos === false) ? $name : substr($name, 0, $pos);
769.             $found        = false;
770.             $loweredAlias = strtolower($alias);
772.             if ($this->namespaces) {
773.                 foreach ($this->namespaces as $namespace) {
774.                     if ($this->classExists($namespace . '\\' . $name)) {
775.                         $name  = $namespace . '\\' . $name;
776.                         $found = true;
777.                         break;
778.                     }
779.                 }
780.             } elseif (isset($this->imports[$loweredAlias])) {
781.                 $namespace = ltrim($this->imports[$loweredAlias], '\\');
782.                 $name      = ($pos !== false)
783.                     ? $namespace . substr($name, $pos)
784.                     : $namespace;
785.                 $found     = $this->classExists($name);
786.             } elseif (
787.                 ! isset($this->ignoredAnnotationNames[$name])
788.                 && isset($this->imports['__NAMESPACE__'])
789.                 && $this->classExists($this->imports['__NAMESPACE__'] . '\\' . $name)
790.             ) {
791.                 $name  = $this->imports['__NAMESPACE__'] . '\\' . $name;
792.                 $found = true;
793.             } elseif (! isset($this->ignoredAnnotationNames[$name]) && $this->classExists($name)) {
794.                 $found = true;
795.             }
797.             if (! $found) {
798.                 if ($this->isIgnoredAnnotation($name)) {
799.                     return false;
800.                 }
802.                 throw AnnotationException::semanticalError(sprintf(
803.                     <<<'EXCEPTION'
804. The annotation "@%s" in %s was never imported. Did you maybe forget to add a "use" statement for this annotation?
805. EXCEPTION
806.                     ,
807.                     $name,
808.                     $this->context
809.                 ));
810.             }
811.         }
813.         $name = ltrim($name, '\\');
815.         if (! $this->classExists($name)) {
816.             throw AnnotationException::semanticalError(sprintf(
817.                 'The annotation "@%s" in %s does not exist, or could not be auto-loaded.',
818.                 $name,
819.                 $this->context
820.             ));
821.         }
823.         // at this point, $name contains the fully qualified class name of the
824.         // annotation, and it is also guaranteed that this class exists, and
825.         // that it is loaded
827.         // collects the metadata annotation only if there is not yet
828.         if (! isset(self::$annotationMetadata[$name])) {
829.             $this->collectAnnotationMetadata($name);
830.         }
832.         // verify that the class is really meant to be an annotation and not just any ordinary class
833.         if (self::$annotationMetadata[$name]['is_annotation'] === false) {
834.             if ($this->isIgnoredAnnotation($originalName) || $this->isIgnoredAnnotation($name)) {
835.                 return false;
836.             }
838.             throw AnnotationException::semanticalError(sprintf(
839.                 <<<'EXCEPTION'
840. The class "%s" is not annotated with @Annotation.
841. Are you sure this class can be used as annotation?
842. If so, then you need to add @Annotation to the _class_ doc comment of "%s".
843. If it is indeed no annotation, then you need to add @IgnoreAnnotation("%s") to the _class_ doc comment of %s.
844. EXCEPTION
845.                 ,
846.                 $name,
847.                 $name,
848.                 $originalName,
849.                 $this->context
850.             ));
851.         }
853.         //if target is nested annotation
854.         $target = $this->isNestedAnnotation ? Target::TARGET_ANNOTATION : $this->target;
856.         // Next will be nested
857.         $this->isNestedAnnotation = true;
859.         //if annotation does not support current target
860.         if ((self::$annotationMetadata[$name]['targets'] & $target) === 0 && $target) {
861.             throw AnnotationException::semanticalError(
862.                 sprintf(
863.                     <<<'EXCEPTION'
864. Annotation @%s is not allowed to be declared on %s. You may only use this annotation on these code elements: %s.
865. EXCEPTION
866.                     ,
867.                     $originalName,
868.                     $this->context,
869.                     self::$annotationMetadata[$name]['targets_literal']
870.                 )
871.             );
872.         }
874.         $arguments = $this->MethodCall();
875.         $values    = $this->resolvePositionalValues($arguments, $name);
877.         if (isset(self::$annotationMetadata[$name]['enum'])) {
878.             // checks all declared attributes
879.             foreach (self::$annotationMetadata[$name]['enum'] as $property => $enum) {
880.                 // checks if the attribute is a valid enumerator
881.                 if (isset($values[$property]) && ! in_array($values[$property], $enum['value'])) {
882.                     throw AnnotationException::enumeratorError(
883.                         $property,
884.                         $name,
885.                         $this->context,
886.                         $enum['literal'],
887.                         $values[$property]
888.                     );
889.                 }
890.             }
891.         }
893.         // checks all declared attributes
894.         foreach (self::$annotationMetadata[$name]['attribute_types'] as $property => $type) {
895.             if (
896.                 $property === self::$annotationMetadata[$name]['default_property']
897.                 && ! isset($values[$property]) && isset($values['value'])
898.             ) {
899.                 $property = 'value';
900.             }
902.             // handle a not given attribute or null value
903.             if (! isset($values[$property])) {
904.                 if ($type['required']) {
905.                     throw AnnotationException::requiredError(
906.                         $property,
907.                         $originalName,
908.                         $this->context,
909.                         'a(n) ' . $type['value']
910.                     );
911.                 }
913.                 continue;
914.             }
916.             if ($type['type'] === 'array') {
917.                 // handle the case of a single value
918.                 if (! is_array($values[$property])) {
919.                     $values[$property] = [$values[$property]];
920.                 }
922.                 // checks if the attribute has array type declaration, such as "array<string>"
923.                 if (isset($type['array_type'])) {
924.                     foreach ($values[$property] as $item) {
925.                         if (gettype($item) !== $type['array_type'] && ! $item instanceof $type['array_type']) {
926.                             throw AnnotationException::attributeTypeError(
927.                                 $property,
928.                                 $originalName,
929.                                 $this->context,
930.                                 'either a(n) ' . $type['array_type'] . ', or an array of ' . $type['array_type'] . 's',
931.                                 $item
932.                             );
933.                         }
934.                     }
935.                 }
936.             } elseif (gettype($values[$property]) !== $type['type'] && ! $values[$property] instanceof $type['type']) {
937.                 throw AnnotationException::attributeTypeError(
938.                     $property,
939.                     $originalName,
940.                     $this->context,
941.                     'a(n) ' . $type['value'],
942.                     $values[$property]
943.                 );
944.             }
945.         }
947.         if (self::$annotationMetadata[$name]['has_named_argument_constructor']) {
948.             if (PHP_VERSION_ID >= 80000) {
949.                 foreach ($values as $property => $value) {
950.                     if (! isset(self::$annotationMetadata[$name]['constructor_args'][$property])) {
951.                         throw AnnotationException::creationError(sprintf(
952.                             <<<'EXCEPTION'
953. The annotation @%s declared on %s does not have a property named "%s"
954. that can be set through its named arguments constructor.
955. Available named arguments: %s
956. EXCEPTION
957.                             ,
958.                             $originalName,
959.                             $this->context,
960.                             $property,
961.                             implode(', ', array_keys(self::$annotationMetadata[$name]['constructor_args']))
962.                         ));
963.                     }
964.                 }
966.                 return $this->instantiateAnnotiation($originalName, $this->context, $name, $values);
967.             }
969.             $positionalValues = [];
970.             foreach (self::$annotationMetadata[$name]['constructor_args'] as $property => $parameter) {
971.                 $positionalValues[$parameter['position']] = $parameter['default'];
972.             }
974.             foreach ($values as $property => $value) {
975.                 if (! isset(self::$annotationMetadata[$name]['constructor_args'][$property])) {
976.                     throw AnnotationException::creationError(sprintf(
977.                         <<<'EXCEPTION'
978. The annotation @%s declared on %s does not have a property named "%s"
979. that can be set through its named arguments constructor.
980. Available named arguments: %s
981. EXCEPTION
982.                         ,
983.                         $originalName,
984.                         $this->context,
985.                         $property,
986.                         implode(', ', array_keys(self::$annotationMetadata[$name]['constructor_args']))
987.                     ));
988.                 }
990.                 $positionalValues[self::$annotationMetadata[$name]['constructor_args'][$property]['position']] = $value;
991.             }
993.             return $this->instantiateAnnotiation($originalName, $this->context, $name, $positionalValues);
994.         }
996.         // check if the annotation expects values via the constructor,
997.         // or directly injected into public properties
998.         if (self::$annotationMetadata[$name]['has_constructor'] === true) {
999.             return $this->instantiateAnnotiation($originalName, $this->context, $name, [$values]);
1000.         }
1002.         $instance = $this->instantiateAnnotiation($originalName, $this->context, $name, []);
1004.         foreach ($values as $property => $value) {
1005.             if (! isset(self::$annotationMetadata[$name]['properties'][$property])) {
1006.                 if ($property !== 'value') {
1007.                     throw AnnotationException::creationError(sprintf(
1008.                         <<<'EXCEPTION'
1009. The annotation @%s declared on %s does not have a property named "%s".
1010. Available properties: %s
1011. EXCEPTION
1012.                         ,
1013.                         $originalName,
1014.                         $this->context,
1015.                         $property,
1016.                         implode(', ', self::$annotationMetadata[$name]['properties'])
1017.                     ));
1018.                 }
1020.                 // handle the case if the property has no annotations
1021.                 $property = self::$annotationMetadata[$name]['default_property'];
1022.                 if (! $property) {
1023.                     throw AnnotationException::creationError(sprintf(
1024.                         'The annotation @%s declared on %s does not accept any values, but got %s.',
1025.                         $originalName,
1026.                         $this->context,
1027.                         json_encode($values)
1028.                     ));
1029.                 }
1030.             }
1032.             $instance->{$property} = $value;
1033.         }
1035.         return $instance;
1036.     }
1038.     /**
1039.      * MethodCall ::= ["(" [Values] ")"]
1040.      *
1041.      * @return mixed[]
1042.      *
1043.      * @throws AnnotationException
1044.      * @throws ReflectionException
1045.      */
1046.     private function MethodCall(): array
1047.     {
1048.         $values = [];
1050.         if (! $this->lexer->isNextToken(DocLexer::T_OPEN_PARENTHESIS)) {
1051.             return $values;
1052.         }
1054.         $this->match(DocLexer::T_OPEN_PARENTHESIS);
1056.         if (! $this->lexer->isNextToken(DocLexer::T_CLOSE_PARENTHESIS)) {
1057.             $values = $this->Values();
1058.         }
1060.         $this->match(DocLexer::T_CLOSE_PARENTHESIS);
1062.         return $values;
1063.     }
1065.     /**
1066.      * Values ::= Array | Value {"," Value}* [","]
1067.      *
1068.      * @return mixed[]
1069.      *
1070.      * @throws AnnotationException
1071.      * @throws ReflectionException
1072.      */
1073.     private function Values(): array
1074.     {
1075.         $values = [$this->Value()];
1077.         while ($this->lexer->isNextToken(DocLexer::T_COMMA)) {
1078.             $this->match(DocLexer::T_COMMA);
1080.             if ($this->lexer->isNextToken(DocLexer::T_CLOSE_PARENTHESIS)) {
1081.                 break;
1082.             }
1084.             $token = $this->lexer->lookahead;
1085.             $value = $this->Value();
1087.             $values[] = $value;
1088.         }
1090.         $namedArguments      = [];
1091.         $positionalArguments = [];
1092.         foreach ($values as $k => $value) {
1093.             if (is_object($value) && $value instanceof stdClass) {
1094.                 $namedArguments[$value->name] = $value->value;
1095.             } else {
1096.                 $positionalArguments[$k] = $value;
1097.             }
1098.         }
1100.         return ['named_arguments' => $namedArguments, 'positional_arguments' => $positionalArguments];
1101.     }
1103.     /**
1104.      * Constant ::= integer | string | float | boolean
1105.      *
1106.      * @return mixed
1107.      *
1108.      * @throws AnnotationException
1109.      */
1110.     private function Constant()
1111.     {
1112.         $identifier = $this->Identifier();
1114.         if (! defined($identifier) && strpos($identifier, '::') !== false && $identifier[0] !== '\\') {
1115.             [$className, $const] = explode('::', $identifier);
1117.             $pos          = strpos($className, '\\');
1118.             $alias        = ($pos === false) ? $className : substr($className, 0, $pos);
1119.             $found        = false;
1120.             $loweredAlias = strtolower($alias);
1122.             switch (true) {
1123.                 case ! empty($this->namespaces):
1124.                     foreach ($this->namespaces as $ns) {
1125.                         if (class_exists($ns . '\\' . $className) || interface_exists($ns . '\\' . $className)) {
1126.                             $className = $ns . '\\' . $className;
1127.                             $found     = true;
1128.                             break;
1129.                         }
1130.                     }
1132.                     break;
1134.                 case isset($this->imports[$loweredAlias]):
1135.                     $found     = true;
1136.                     $className = ($pos !== false)
1137.                         ? $this->imports[$loweredAlias] . substr($className, $pos)
1138.                         : $this->imports[$loweredAlias];
1139.                     break;
1141.                 default:
1142.                     if (isset($this->imports['__NAMESPACE__'])) {
1143.                         $ns = $this->imports['__NAMESPACE__'];
1145.                         if (class_exists($ns . '\\' . $className) || interface_exists($ns . '\\' . $className)) {
1146.                             $className = $ns . '\\' . $className;
1147.                             $found     = true;
1148.                         }
1149.                     }
1151.                     break;
1152.             }
1154.             if ($found) {
1155.                 $identifier = $className . '::' . $const;
1156.             }
1157.         }
1159.         /**
1160.          * Checks if identifier ends with ::class and remove the leading backslash if it exists.
1161.          */
1162.         if (
1163.             $this->identifierEndsWithClassConstant($identifier) &&
1164.             ! $this->identifierStartsWithBackslash($identifier)
1165.         ) {
1166.             return substr($identifier, 0, $this->getClassConstantPositionInIdentifier($identifier));
1167.         }
1169.         if ($this->identifierEndsWithClassConstant($identifier) && $this->identifierStartsWithBackslash($identifier)) {
1170.             return substr($identifier, 1, $this->getClassConstantPositionInIdentifier($identifier) - 1);
1171.         }
1173.         if (! defined($identifier)) {
1174.             throw AnnotationException::semanticalErrorConstants($identifier, $this->context);
1175.         }
1177.         return constant($identifier);
1178.     }
1180.     private function identifierStartsWithBackslash(string $identifier): bool
1181.     {
1182.         return $identifier[0] === '\\';
1183.     }
1185.     private function identifierEndsWithClassConstant(string $identifier): bool
1186.     {
1187.         return $this->getClassConstantPositionInIdentifier($identifier) === strlen($identifier) - strlen('::class');
1188.     }
1190.     /** @return int|false */
1191.     private function getClassConstantPositionInIdentifier(string $identifier)
1192.     {
1193.         return stripos($identifier, '::class');
1194.     }
1196.     /**
1197.      * Identifier ::= string
1198.      *
1199.      * @throws AnnotationException
1200.      */
1201.     private function Identifier(): string
1202.     {
1203.         // check if we have an annotation
1204.         if (! $this->lexer->isNextTokenAny(self::$classIdentifiers)) {
1205.             throw $this->syntaxError('namespace separator or identifier');
1206.         }
1208.         $this->lexer->moveNext();
1210.         $className = $this->lexer->token['value'];
1212.         while (
1213.             $this->lexer->lookahead !== null &&
1214.             $this->lexer->lookahead['position'] === ($this->lexer->token['position'] +
1215.             strlen($this->lexer->token['value'])) &&
1216.             $this->lexer->isNextToken(DocLexer::T_NAMESPACE_SEPARATOR)
1217.         ) {
1218.             $this->match(DocLexer::T_NAMESPACE_SEPARATOR);
1219.             $this->matchAny(self::$classIdentifiers);
1221.             $className .= '\\' . $this->lexer->token['value'];
1222.         }
1224.         return $className;
1225.     }
1227.     /**
1228.      * Value ::= PlainValue | FieldAssignment
1229.      *
1230.      * @return mixed
1231.      *
1232.      * @throws AnnotationException
1233.      * @throws ReflectionException
1234.      */
1235.     private function Value()
1236.     {
1237.         $peek = $this->lexer->glimpse();
1239.         if ($peek['type'] === DocLexer::T_EQUALS) {
1240.             return $this->FieldAssignment();
1241.         }
1243.         return $this->PlainValue();
1244.     }
1246.     /**
1247.      * PlainValue ::= integer | string | float | boolean | Array | Annotation
1248.      *
1249.      * @return mixed
1250.      *
1251.      * @throws AnnotationException
1252.      * @throws ReflectionException
1253.      */
1254.     private function PlainValue()
1255.     {
1256.         if ($this->lexer->isNextToken(DocLexer::T_OPEN_CURLY_BRACES)) {
1257.             return $this->Arrayx();
1258.         }
1260.         if ($this->lexer->isNextToken(DocLexer::T_AT)) {
1261.             return $this->Annotation();
1262.         }
1264.         if ($this->lexer->isNextToken(DocLexer::T_IDENTIFIER)) {
1265.             return $this->Constant();
1266.         }
1268.         switch ($this->lexer->lookahead['type']) {
1269.             case DocLexer::T_STRING:
1270.                 $this->match(DocLexer::T_STRING);
1272.                 return $this->lexer->token['value'];
1274.             case DocLexer::T_INTEGER:
1275.                 $this->match(DocLexer::T_INTEGER);
1277.                 return (int) $this->lexer->token['value'];
1279.             case DocLexer::T_FLOAT:
1280.                 $this->match(DocLexer::T_FLOAT);
1282.                 return (float) $this->lexer->token['value'];
1284.             case DocLexer::T_TRUE:
1285.                 $this->match(DocLexer::T_TRUE);
1287.                 return true;
1289.             case DocLexer::T_FALSE:
1290.                 $this->match(DocLexer::T_FALSE);
1292.                 return false;
1294.             case DocLexer::T_NULL:
1295.                 $this->match(DocLexer::T_NULL);
1297.                 return null;
1299.             default:
1300.                 throw $this->syntaxError('PlainValue');
1301.         }
1302.     }
1304.     /**
1305.      * FieldAssignment ::= FieldName "=" PlainValue
1306.      * FieldName ::= identifier
1307.      *
1308.      * @throws AnnotationException
1309.      * @throws ReflectionException
1310.      */
1311.     private function FieldAssignment(): stdClass
1312.     {
1313.         $this->match(DocLexer::T_IDENTIFIER);
1314.         $fieldName = $this->lexer->token['value'];
1316.         $this->match(DocLexer::T_EQUALS);
1318.         $item        = new stdClass();
1319.         $item->name  = $fieldName;
1320.         $item->value = $this->PlainValue();
1322.         return $item;
1323.     }
1325.     /**
1326.      * Array ::= "{" ArrayEntry {"," ArrayEntry}* [","] "}"
1327.      *
1328.      * @return mixed[]
1329.      *
1330.      * @throws AnnotationException
1331.      * @throws ReflectionException
1332.      */
1333.     private function Arrayx(): array
1334.     {
1335.         $array = $values = [];
1337.         $this->match(DocLexer::T_OPEN_CURLY_BRACES);
1339.         // If the array is empty, stop parsing and return.
1340.         if ($this->lexer->isNextToken(DocLexer::T_CLOSE_CURLY_BRACES)) {
1341.             $this->match(DocLexer::T_CLOSE_CURLY_BRACES);
1343.             return $array;
1344.         }
1346.         $values[] = $this->ArrayEntry();
1348.         while ($this->lexer->isNextToken(DocLexer::T_COMMA)) {
1349.             $this->match(DocLexer::T_COMMA);
1351.             // optional trailing comma
1352.             if ($this->lexer->isNextToken(DocLexer::T_CLOSE_CURLY_BRACES)) {
1353.                 break;
1354.             }
1356.             $values[] = $this->ArrayEntry();
1357.         }
1359.         $this->match(DocLexer::T_CLOSE_CURLY_BRACES);
1361.         foreach ($values as $value) {
1362.             [$key, $val] = $value;
1364.             if ($key !== null) {
1365.                 $array[$key] = $val;
1366.             } else {
1367.                 $array[] = $val;
1368.             }
1369.         }
1371.         return $array;
1372.     }
1374.     /**
1375.      * ArrayEntry ::= Value | KeyValuePair
1376.      * KeyValuePair ::= Key ("=" | ":") PlainValue | Constant
1377.      * Key ::= string | integer | Constant
1378.      *
1379.      * @phpstan-return array{mixed, mixed}
1380.      *
1381.      * @throws AnnotationException
1382.      * @throws ReflectionException
1383.      */
1384.     private function ArrayEntry(): array
1385.     {
1386.         $peek = $this->lexer->glimpse();
1388.         if (
1389.             $peek['type'] === DocLexer::T_EQUALS
1390.                 || $peek['type'] === DocLexer::T_COLON
1391.         ) {
1392.             if ($this->lexer->isNextToken(DocLexer::T_IDENTIFIER)) {
1393.                 $key = $this->Constant();
1394.             } else {
1395.                 $this->matchAny([DocLexer::T_INTEGER, DocLexer::T_STRING]);
1396.                 $key = $this->lexer->token['value'];
1397.             }
1399.             $this->matchAny([DocLexer::T_EQUALS, DocLexer::T_COLON]);
1401.             return [$key, $this->PlainValue()];
1402.         }
1404.         return [null, $this->Value()];
1405.     }
1407.     /**
1408.      * Checks whether the given $name matches any ignored annotation name or namespace
1409.      */
1410.     private function isIgnoredAnnotation(string $name): bool
1411.     {
1412.         if ($this->ignoreNotImportedAnnotations || isset($this->ignoredAnnotationNames[$name])) {
1413.             return true;
1414.         }
1416.         foreach (array_keys($this->ignoredAnnotationNamespaces) as $ignoredAnnotationNamespace) {
1417.             $ignoredAnnotationNamespace = rtrim($ignoredAnnotationNamespace, '\\') . '\\';
1419.             if (stripos(rtrim($name, '\\') . '\\', $ignoredAnnotationNamespace) === 0) {
1420.                 return true;
1421.             }
1422.         }
1424.         return false;
1425.     }
1427.     /**
1428.      * Resolve positional arguments (without name) to named ones
1429.      *
1430.      * @param array<string,mixed> $arguments
1431.      *
1432.      * @return array<string,mixed>
1433.      */
1434.     private function resolvePositionalValues(array $arguments, string $name): array
1435.     {
1436.         $positionalArguments = $arguments['positional_arguments'] ?? [];
1437.         $values              = $arguments['named_arguments'] ?? [];
1439.         if (
1440.             self::$annotationMetadata[$name]['has_named_argument_constructor']
1441.             && self::$annotationMetadata[$name]['default_property'] !== null
1442.         ) {
1443.             // We must ensure that we don't have positional arguments after named ones
1444.             $positions    = array_keys($positionalArguments);
1445.             $lastPosition = null;
1446.             foreach ($positions as $position) {
1447.                 if (
1448.                     ($lastPosition === null && $position !== 0) ||
1449.                     ($lastPosition !== null && $position !== $lastPosition + 1)
1450.                 ) {
1451.                     throw $this->syntaxError('Positional arguments after named arguments is not allowed');
1452.                 }
1454.                 $lastPosition = $position;
1455.             }
1457.             foreach (self::$annotationMetadata[$name]['constructor_args'] as $property => $parameter) {
1458.                 $position = $parameter['position'];
1459.                 if (isset($values[$property]) || ! isset($positionalArguments[$position])) {
1460.                     continue;
1461.                 }
1463.                 $values[$property] = $positionalArguments[$position];
1464.             }
1465.         } else {
1466.             if (count($positionalArguments) > 0 && ! isset($values['value'])) {
1467.                 if (count($positionalArguments) === 1) {
1468.                     $value = array_pop($positionalArguments);
1469.                 } else {
1470.                     $value = array_values($positionalArguments);
1471.                 }
1473.                 $values['value'] = $value;
1474.             }
1475.         }
1477.         return $values;
1478.     }
1480.     /**
1481.      * Try to instantiate the annotation and catch and process any exceptions related to failure
1482.      *
1483.      * @param class-string        $name
1484.      * @param array<string,mixed> $arguments
1485.      *
1486.      * @return object
1487.      *
1488.      * @throws AnnotationException
1489.      */
1490.     private function instantiateAnnotiation(string $originalName, string $context, string $name, array $arguments)
1491.     {
1492.         try {
1493.             return new $name(...$arguments);
1494.         } catch (Throwable $exception) {
1495.             throw AnnotationException::creationError(
1496.                 sprintf(
1497.                     'An error occurred while instantiating the annotation @%s declared on %s: "%s".',
1498.                     $originalName,
1499.                     $context,
1500.                     $exception->getMessage()
1501.                 ),
1502.                 $exception
1503.             );
1504.         }
1505.     }
1506. }