vendor/zircote/swagger-php/src/Annotations/AbstractAnnotation.php line 100

Open in your IDE?
  1. <?php declare(strict_types=1);
  3. /**
  4.  * @license Apache 2.0
  5.  */
  7. namespace OpenApi\Annotations;
  9. use OpenApi\Analyser;
  10. use OpenApi\Context;
  11. use OpenApi\Generator;
  12. use OpenApi\Util;
  13. use Symfony\Component\Yaml\Yaml;
  15. /**
  16.  * The openapi annotation base class.
  17.  */
  18. abstract class AbstractAnnotation implements \JsonSerializable
  19. {
  20.     /**
  21.      * While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
  22.      * For further details see https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#specificationExtensions
  23.      * The keys inside the array will be prefixed with `x-`.
  24.      *
  25.      * @var array
  26.      */
  27.     public $x = Generator::UNDEFINED;
  29.     /**
  30.      * Arbitrary attachables for this annotation.
  31.      * These will be ignored but can be used for custom processing.
  32.      */
  33.     public $attachables = Generator::UNDEFINED;
  35.     /**
  36.      * @var Context
  37.      */
  38.     public $_context;
  40.     /**
  41.      * Annotations that couldn't be merged by mapping or postprocessing.
  42.      *
  43.      * @var array
  44.      */
  45.     public $_unmerged = [];
  47.     /**
  48.      * The properties which are required by [the spec](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md).
  49.      *
  50.      * @var array
  51.      */
  52.     public static $_required = [];
  54.     /**
  55.      * Specify the type of the property.
  56.      * Examples:
  57.      *   'name' => 'string' // a string
  58.      *   'required' => 'boolean', // true or false
  59.      *   'tags' => '[string]', // array containing strings
  60.      *   'in' => ["query", "header", "path", "formData", "body"] // must be one on these
  61.      *   'oneOf' => [Schema::class] // array of schema objects.
  62.      *
  63.      * @var array
  64.      */
  65.     public static $_types = [];
  67.     /**
  68.      * Declarative mapping of Annotation types to properties.
  69.      * Examples:
  70.      *   Info::clas => 'info', // Set @OA\Info annotation as the info property.
  71.      *   Parameter::clas => ['parameters'],  // Append @OA\Parameter annotations the parameters array.
  72.      *   PathItem::clas => ['paths', 'path'],  // Append @OA\PathItem annotations the paths array and use path as key.
  73.      *
  74.      * @var array
  75.      */
  76.     public static $_nested = [];
  78.     /**
  79.      * Reverse mapping of $_nested with the allowed parent annotations.
  80.      *
  81.      * @var string[]
  82.      */
  83.     public static $_parents = [];
  85.     /**
  86.      * List of properties are blacklisted from the JSON output.
  87.      *
  88.      * @var array
  89.      */
  90.     public static $_blacklist = ['_context', '_unmerged', 'attachables'];
  92.     public function __construct(array $properties)
  93.     {
  94.         if (isset($properties['_context'])) {
  95.             $this->_context = $properties['_context'];
  96.             unset($properties['_context']);
  97.         } elseif (Analyser::$context) {
  98.             $this->_context = Analyser::$context;
  99.         } else {
  100.             $this->_context = Context::detect(1);
  101.         }
  102.         if ($this->_context->is('annotations') === false) {
  103.             $this->_context->annotations = [];
  104.         }
  105.         $this->_context->annotations[] = $this;
  106.         $nestedContext = new Context(['nested' => $this], $this->_context);
  107.         foreach ($properties as $property => $value) {
  108.             if (property_exists($this, $property)) {
  109.                 $this->$property = $value;
  110.                 if (is_array($value)) {
  111.                     foreach ($value as $key => $annotation) {
  112.                         if (is_object($annotation) && $annotation instanceof AbstractAnnotation) {
  113.                             $this->$property[$key] = $this->nested($annotation, $nestedContext);
  114.                         }
  115.                     }
  116.                 }
  117.             } elseif ($property !== 'value') {
  118.                 $this->$property = $value;
  119.             } elseif (is_array($value)) {
  120.                 $annotations = [];
  121.                 foreach ($value as $annotation) {
  122.                     if (is_object($annotation) && $annotation instanceof AbstractAnnotation) {
  123.                         $annotations[] = $annotation;
  124.                     } else {
  125.                         $this->_context->logger->warning('Unexpected field in ' . $this->identity() . ' in ' . $this->_context);
  126.                     }
  127.                 }
  128.                 $this->merge($annotations);
  129.             } elseif (is_object($value)) {
  130.                 $this->merge([$value]);
  131.             } else {
  132.                 $this->_context->logger->warning('Unexpected parameter in ' . $this->identity());
  133.             }
  134.         }
  135.     }
  137.     public function __get($property)
  138.     {
  139.         $properties = get_object_vars($this);
  140.         $this->_context->logger->warning('Property "' . $property . '" doesn\'t exist in a ' . $this->identity() . ', existing properties: "' . implode('", "', array_keys($properties)) . '" in ' . $this->_context);
  141.     }
  143.     public function __set($property, $value)
  144.     {
  145.         $fields = get_object_vars($this);
  146.         foreach (static::$_blacklist as $_property) {
  147.             unset($fields[$_property]);
  148.         }
  149.         $this->_context->logger->warning('Unexpected field "' . $property . '" for ' . $this->identity() . ', expecting "' . implode('", "', array_keys($fields)) . '" in ' . $this->_context);
  150.         $this->$property = $value;
  151.     }
  153.     /**
  154.      * Merge given annotations to their mapped properties configured in static::$_nested.
  155.      *
  156.      * Annotations that couldn't be merged are added to the _unmerged array.
  157.      *
  158.      * @param AbstractAnnotation[] $annotations
  159.      * @param bool                 $ignore      Ignore unmerged annotations
  160.      *
  161.      * @return AbstractAnnotation[] The unmerged annotations
  162.      */
  163.     public function merge(array $annotations, bool $ignore = false): array
  164.     {
  165.         $unmerged = [];
  166.         $nestedContext = new Context(['nested' => $this], $this->_context);
  168.         foreach ($annotations as $annotation) {
  169.             $mapped = false;
  170.             if ($details = static::matchNested(get_class($annotation))) {
  171.                 $property = $details->value;
  172.                 if (is_array($property)) {
  173.                     $property = $property[0];
  174.                     if ($this->$property === Generator::UNDEFINED) {
  175.                         $this->$property = [];
  176.                     }
  177.                     $this->$property[] = $this->nested($annotation, $nestedContext);
  178.                     $mapped = true;
  179.                 } elseif ($this->$property === Generator::UNDEFINED) {
  180.                     // ignore duplicate nested if only one expected
  181.                     $this->$property = $this->nested($annotation, $nestedContext);
  182.                     $mapped = true;
  183.                 }
  184.             }
  185.             if (!$mapped) {
  186.                 $unmerged[] = $annotation;
  187.             }
  188.         }
  189.         if (!$ignore) {
  190.             foreach ($unmerged as $annotation) {
  191.                 $this->_unmerged[] = $this->nested($annotation, $nestedContext);
  192.             }
  193.         }
  195.         return $unmerged;
  196.     }
  198.     /**
  199.      * Merge the properties from the given object into this annotation.
  200.      * Prevents overwriting properties that are already configured.
  201.      *
  202.      * @param object $object
  203.      */
  204.     public function mergeProperties($object): void
  205.     {
  206.         $defaultValues = get_class_vars(get_class($this));
  207.         $currentValues = get_object_vars($this);
  208.         foreach ($object as $property => $value) {
  209.             if ($property === '_context') {
  210.                 continue;
  211.             }
  212.             if ($currentValues[$property] === $defaultValues[$property]) { // Overwrite default values
  213.                 $this->$property = $value;
  214.                 continue;
  215.             }
  216.             if ($property === '_unmerged') {
  217.                 $this->_unmerged = array_merge($this->_unmerged, $value);
  218.                 continue;
  219.             }
  220.             if ($currentValues[$property] !== $value) { // New value is not the same?
  221.                 if ($defaultValues[$property] === $value) { // but is the same as the default?
  222.                     continue; // Keep current, no notice
  223.                 }
  224.                 $identity = method_exists($object, 'identity') ? $object->identity() : get_class($object);
  225.                 $context1 = $this->_context;
  226.                 $context2 = property_exists($object, '_context') ? $object->_context : 'unknown';
  227.                 if (is_object($this->$property) && $this->{$property} instanceof AbstractAnnotation) {
  228.                     $context1 = $this->$property->_context;
  229.                 }
  230.                 $this->_context->logger->error('Multiple definitions for ' . $identity . '->' . $property . "\n     Using: " . $context1 . "\n  Skipping: " . $context2);
  231.             }
  232.         }
  233.     }
  235.     /**
  236.      * Generate the documentation in YAML format.
  237.      */
  238.     public function toYaml($flags = null): string
  239.     {
  240.         if ($flags === null) {
  241.             $flags = Yaml::DUMP_OBJECT_AS_MAP ^ Yaml::DUMP_EMPTY_ARRAY_AS_SEQUENCE;
  242.         }
  244.         return Yaml::dump(json_decode($this->toJson(JSON_INVALID_UTF8_IGNORE)), 10, 2, $flags);
  245.     }
  247.     /**
  248.      * Generate the documentation in YAML format.
  249.      */
  250.     public function toJson($flags = null): string
  251.     {
  252.         if ($flags === null) {
  253.             $flags = JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE | JSON_INVALID_UTF8_IGNORE;
  254.         }
  256.         return json_encode($this, $flags);
  257.     }
  259.     public function __debugInfo()
  260.     {
  261.         $properties = [];
  262.         foreach (get_object_vars($this) as $property => $value) {
  263.             if ($value !== Generator::UNDEFINED) {
  264.                 $properties[$property] = $value;
  265.             }
  266.         }
  268.         return $properties;
  269.     }
  271.     /**
  272.      * Customize the way json_encode() renders the annotations.
  273.      *
  274.      * @return mixed
  275.      */
  276.     #[\ReturnTypeWillChange]
  277.     public function jsonSerialize()
  278.     {
  279.         $data = new \stdClass();
  281.         // Strip undefined values.
  282.         foreach (get_object_vars($this) as $property => $value) {
  283.             if ($value !== Generator::UNDEFINED) {
  284.                 $data->$property = $value;
  285.             }
  286.         }
  288.         // Strip properties that are for internal (swagger-php) use.
  289.         foreach (static::$_blacklist as $property) {
  290.             unset($data->$property);
  291.         }
  293.         // Correct empty array to empty objects.
  294.         foreach (static::$_types as $property => $type) {
  295.             if ($type === 'object' && is_array($data->$property) && empty($data->$property)) {
  296.                 $data->$property = new \stdClass();
  297.             }
  298.         }
  300.         // Inject vendor properties.
  301.         unset($data->x);
  302.         if (is_array($this->x)) {
  303.             foreach ($this->x as $property => $value) {
  304.                 $prefixed = 'x-' . $property;
  305.                 $data->$prefixed = $value;
  306.             }
  307.         }
  309.         // Map nested keys
  310.         foreach (static::$_nested as $nested) {
  311.             if (is_string($nested) || count($nested) === 1) {
  312.                 continue;
  313.             }
  314.             $property = $nested[0];
  315.             if ($this->$property === Generator::UNDEFINED) {
  316.                 continue;
  317.             }
  318.             $keyField = $nested[1];
  319.             $object = new \stdClass();
  320.             foreach ($this->$property as $key => $item) {
  321.                 if (is_numeric($key) === false && is_array($item)) {
  322.                     $object->$key = $item;
  323.                 } else {
  324.                     $key = $item->$keyField;
  325.                     if ($key !== Generator::UNDEFINED && empty($object->$key)) {
  326.                         if ($item instanceof \JsonSerializable) {
  327.                             $object->$key = $item->jsonSerialize();
  328.                         } else {
  329.                             $object->$key = $item;
  330.                         }
  331.                         unset($object->$key->$keyField);
  332.                     }
  333.                 }
  334.             }
  335.             $data->$property = $object;
  336.         }
  338.         // $ref
  339.         if (isset($data->ref)) {
  340.             // OAS 3.0 does not allow $ref to have siblings: http://spec.openapis.org/oas/v3.0.3#fixed-fields-18
  341.             $data = (object) ['$ref' => $data->ref];
  342.         }
  344.         return $data;
  345.     }
  347.     /**
  348.      * Validate annotation tree, and log notices & warnings.
  349.      *
  350.      * @param array $parents the path of annotations above this annotation in the tree
  351.      * @param array $skip    (prevent stack overflow, when traversing an infinite dependency graph)
  352.      */
  353.     public function validate(array $parents = [], array $skip = [], string $ref = ''): bool
  354.     {
  355.         if (in_array($this, $skip, true)) {
  356.             return true;
  357.         }
  358.         $valid = true;
  360.         // Report orphaned annotations
  361.         foreach ($this->_unmerged as $annotation) {
  362.             if (!is_object($annotation)) {
  363.                 $this->_context->logger->warning('Unexpected type: "' . gettype($annotation) . '" in ' . $this->identity() . '->_unmerged, expecting a Annotation object');
  364.                 break;
  365.             }
  367.             $class = get_class($annotation);
  368.             if ($details = static::matchNested($class)) {
  369.                 $property = $details->value;
  370.                 if (is_array($property)) {
  371.                     $this->_context->logger->warning('Only one ' . Util::shorten(get_class($annotation)) . '() allowed for ' . $this->identity() . ' multiple found, skipped: ' . $annotation->_context);
  372.                 } else {
  373.                     $this->_context->logger->warning('Only one ' . Util::shorten(get_class($annotation)) . '() allowed for ' . $this->identity() . " multiple found in:\n    Using: " . $this->$property->_context . "\n  Skipped: " . $annotation->_context);
  374.                 }
  375.             } elseif ($annotation instanceof AbstractAnnotation) {
  376.                 $message = 'Unexpected ' . $annotation->identity();
  377.                 if ($class::$_parents) {
  378.                     $message .= ', expected to be inside ' . implode(', ', Util::shorten($class::$_parents));
  379.                 }
  380.                 $this->_context->logger->warning($message . ' in ' . $annotation->_context);
  381.             }
  382.             $valid = false;
  383.         }
  385.         // Report conflicting key
  386.         foreach (static::$_nested as $annotationClass => $nested) {
  387.             if (is_string($nested) || count($nested) === 1) {
  388.                 continue;
  389.             }
  390.             $property = $nested[0];
  391.             if ($this->$property === Generator::UNDEFINED) {
  392.                 continue;
  393.             }
  394.             $keys = [];
  395.             $keyField = $nested[1];
  396.             foreach ($this->$property as $key => $item) {
  397.                 if (is_array($item) && is_numeric($key) === false) {
  398.                     $this->_context->logger->warning($this->identity() . '->' . $property . ' is an object literal, use nested ' . Util::shorten($annotationClass) . '() annotation(s) in ' . $this->_context);
  399.                     $keys[$key] = $item;
  400.                 } elseif ($item->$keyField === Generator::UNDEFINED) {
  401.                     $this->_context->logger->error($item->identity() . ' is missing key-field: "' . $keyField . '" in ' . $item->_context);
  402.                 } elseif (isset($keys[$item->$keyField])) {
  403.                     $this->_context->logger->error('Multiple ' . $item->_identity([]) . ' with the same ' . $keyField . '="' . $item->$keyField . "\":\n  " . $item->_context . "\n  " . $keys[$item->$keyField]->_context);
  404.                 } else {
  405.                     $keys[$item->$keyField] = $item;
  406.                 }
  407.             }
  408.         }
  409.         if (property_exists($this, 'ref') && $this->ref !== Generator::UNDEFINED && $this->ref !== null) {
  410.             if (substr($this->ref, 0, 2) === '#/' && count($parents) > 0 && $parents[0] instanceof OpenApi) {
  411.                 // Internal reference
  412.                 try {
  413.                     $parents[0]->ref($this->ref);
  414.                 } catch (\Exception $e) {
  415.                     $this->_context->logger->warning($e->getMessage() . ' for ' . $this->identity() . ' in ' . $this->_context, ['exception' => $e]);
  416.                 }
  417.             }
  418.         } else {
  419.             // Report missing required fields (when not a $ref)
  420.             foreach (static::$_required as $property) {
  421.                 if ($this->$property === Generator::UNDEFINED) {
  422.                     $message = 'Missing required field "' . $property . '" for ' . $this->identity() . ' in ' . $this->_context;
  423.                     foreach (static::$_nested as $class => $nested) {
  424.                         $nestedProperty = is_array($nested) ? $nested[0] : $nested;
  425.                         if ($property === $nestedProperty) {
  426.                             if ($this instanceof OpenApi) {
  427.                                 $message = 'Required ' . Util::shorten($class) . '() not found';
  428.                             } elseif (is_array($nested)) {
  429.                                 $message = $this->identity() . ' requires at least one ' . Util::shorten($class) . '() in ' . $this->_context;
  430.                             } else {
  431.                                 $message = $this->identity() . ' requires a ' . Util::shorten($class) . '() in ' . $this->_context;
  432.                             }
  433.                             break;
  434.                         }
  435.                     }
  436.                     $this->_context->logger->warning($message);
  437.                 }
  438.             }
  439.         }
  441.         // Report invalid types
  442.         foreach (static::$_types as $property => $type) {
  443.             $value = $this->$property;
  444.             if ($value === Generator::UNDEFINED || $value === null) {
  445.                 continue;
  446.             }
  447.             if (is_string($type)) {
  448.                 if ($this->validateType($type, $value) === false) {
  449.                     $valid = false;
  450.                     $this->_context->logger->warning($this->identity() . '->' . $property . ' is a "' . gettype($value) . '", expecting a "' . $type . '" in ' . $this->_context);
  451.                 }
  452.             } elseif (is_array($type)) { // enum?
  453.                 if (in_array($value, $type) === false) {
  454.                     $this->_context->logger->warning($this->identity() . '->' . $property . ' "' . $value . '" is invalid, expecting "' . implode('", "', $type) . '" in ' . $this->_context);
  455.                 }
  456.             } else {
  457.                 throw new \Exception('Invalid ' . get_class($this) . '::$_types[' . $property . ']');
  458.             }
  459.         }
  460.         $parents[] = $this;
  462.         return self::_validate($this, $parents, $skip, $ref) ? $valid : false;
  463.     }
  465.     /**
  466.      * Recursively validate all annotation properties.
  467.      *
  468.      * @param array|object $fields
  469.      * @param array        $parents the path of annotations above this annotation in the tree
  470.      * @param array        $skip    List of objects already validated
  471.      */
  472.     private static function _validate($fields, array $parents, array $skip, string $baseRef): bool
  473.     {
  474.         $valid = true;
  475.         $blacklist = [];
  476.         if (is_object($fields)) {
  477.             if (in_array($fields, $skip, true)) {
  478.                 return true;
  479.             }
  480.             $skip[] = $fields;
  481.             $blacklist = property_exists($fields, '_blacklist') ? $fields::$_blacklist : [];
  482.         }
  484.         foreach ($fields as $field => $value) {
  485.             if ($value === null || is_scalar($value) || in_array($field, $blacklist)) {
  486.                 continue;
  487.             }
  488.             $ref = $baseRef !== '' ? $baseRef . '/' . urlencode((string) $field) : urlencode((string) $field);
  489.             if (is_object($value)) {
  490.                 if (method_exists($value, 'validate')) {
  491.                     if (!$value->validate($parents, $skip, $ref)) {
  492.                         $valid = false;
  493.                     }
  494.                 } elseif (!self::_validate($value, $parents, $skip, $ref)) {
  495.                     $valid = false;
  496.                 }
  497.             } elseif (is_array($value) && !self::_validate($value, $parents, $skip, $ref)) {
  498.                 $valid = false;
  499.             }
  500.         }
  502.         return $valid;
  503.     }
  505.     /**
  506.      * Return a identity for easy debugging.
  507.      * Example: "@OA\Get(path="/pets")".
  508.      */
  509.     public function identity(): string
  510.     {
  511.         $class = get_class($this);
  512.         $properties = [];
  513.         foreach (static::$_parents as $parent) {
  514.             foreach ($parent::$_nested as $annotationClass => $entry) {
  515.                 if ($annotationClass === $class && is_array($entry) && $this->{$entry[1]} !== Generator::UNDEFINED) {
  516.                     $properties[] = $entry[1];
  517.                     break 2;
  518.                 }
  519.             }
  520.         }
  522.         return $this->_identity($properties);
  523.     }
  525.     /**
  526.      * An annotation is a root if it is the top-level / outermost annotation in a PHP docblock.
  527.      */
  528.     public function isRoot(): bool
  529.     {
  530.         if (!$this->_context) {
  531.             return true;
  532.         }
  534.         $count = count($this->_context->annotations);
  536.         return $count && $this->_context->annotations[$count - 1] === $this;
  537.     }
  539.     /**
  540.      * Find matching nested details.
  541.      *
  542.      * @param string $class the class to match
  543.      *
  544.      * @return null|object key/value object or `null`
  545.      */
  546.     public static function matchNested(string $class)
  547.     {
  548.         if (array_key_exists($class, static::$_nested)) {
  549.             return (object) ['key' => $class, 'value' => static::$_nested[$class]];
  550.         }
  552.         $parent = $class;
  553.         // only consider the immediate OpenApi parent
  554.         while (0 !== strpos($parent, 'OpenApi\\Annotations\\') && $parent = get_parent_class($parent)) {
  555.             if ($kvp = static::matchNested($parent)) {
  556.                 return $kvp;
  557.             }
  558.         }
  560.         return null;
  561.     }
  563.     /**
  564.      * Helper for generating the identity().
  565.      */
  566.     protected function _identity(array $properties): string
  567.     {
  568.         $fields = [];
  569.         foreach ($properties as $property) {
  570.             $value = $this->$property;
  571.             if ($value !== null && $value !== Generator::UNDEFINED) {
  572.                 $fields[] = $property . '=' . (is_string($value) ? '"' . $value . '"' : $value);
  573.             }
  574.         }
  576.         return Util::shorten(get_class($this)) . '(' . implode(',', $fields) . ')';
  577.     }
  579.     /**
  580.      * Validates the matching of the property value to a annotation type.
  581.      *
  582.      * @param string $type  The annotations property type
  583.      * @param mixed  $value The property value
  584.      */
  585.     private function validateType(string $type, $value): bool
  586.     {
  587.         if (substr($type, 0, 1) === '[' && substr($type, -1) === ']') { // Array of a specified type?
  588.             if ($this->validateType('array', $value) === false) {
  589.                 return false;
  590.             }
  591.             $itemType = substr($type, 1, -1);
  592.             foreach ($value as $i => $item) {
  593.                 if ($this->validateType($itemType, $item) === false) {
  594.                     return false;
  595.                 }
  596.             }
  598.             return true;
  599.         }
  601.         if (is_subclass_of($type, AbstractAnnotation::class)) {
  602.             $type = 'object';
  603.         }
  605.         return $this->validateDefaultTypes($type, $value);
  606.     }
  608.     /**
  609.      * Validates default Open Api types.
  610.      *
  611.      * @param string $type  The property type
  612.      * @param mixed  $value The value to validate
  613.      */
  614.     private function validateDefaultTypes(string $type, $value): bool
  615.     {
  616.         switch ($type) {
  617.             case 'string':
  618.                 return is_string($value);
  619.             case 'boolean':
  620.                 return is_bool($value);
  621.             case 'integer':
  622.                 return is_int($value);
  623.             case 'number':
  624.                 return is_numeric($value);
  625.             case 'object':
  626.                 return is_object($value);
  627.             case 'array':
  628.                 return $this->validateArrayType($value);
  629.             case 'scheme':
  630.                 return in_array($value, ['http', 'https', 'ws', 'wss'], true);
  631.             default:
  632.                 throw new \Exception('Invalid type "' . $type . '"');
  633.         }
  634.     }
  636.     /**
  637.      * Validate array type.
  638.      */
  639.     private function validateArrayType($value): bool
  640.     {
  641.         if (is_array($value) === false) {
  642.             return false;
  643.         }
  644.         $count = 0;
  645.         foreach ($value as $i => $item) {
  646.             //not a array, but a hash/map
  647.             if ($count !== $i) {
  648.                 return false;
  649.             }
  650.             $count++;
  651.         }
  653.         return true;
  654.     }
  656.     /**
  657.      * Wrap the context with a reference to the annotation it is nested in.
  658.      *
  659.      * @param AbstractAnnotation $annotation
  660.      *
  661.      * @return AbstractAnnotation
  662.      */
  663.     private function nested($annotation, Context $nestedContext)
  664.     {
  665.         if (property_exists($annotation, '_context') && $annotation->_context === $this->_context) {
  666.             $annotation->_context = $nestedContext;
  667.         }
  669.         return $annotation;
  670.     }
  671. }