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

Open in your IDE?
  1. <?php declare(strict_types=1);
  3. /**
  4.  * @license Apache 2.0
  5.  */
  7. namespace OpenApi\Annotations;
  9. use OpenApi\Context;
  10. use OpenApi\Generator;
  11. use OpenApi\Annotations as OA;
  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/main/versions/3.1.0.md#specificationExtensions
  23.      * The keys inside the array will be prefixed with `x-`.
  24.      *
  25.      * @var array<string,mixed>
  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.      * @var array
  34.      */
  35.     public $attachables = Generator::UNDEFINED;
  37.     /**
  38.      * @var Context|null
  39.      */
  40.     public $_context = null;
  42.     /**
  43.      * Annotations that couldn't be merged by mapping or postprocessing.
  44.      *
  45.      * @var array
  46.      */
  47.     public $_unmerged = [];
  49.     /**
  50.      * The properties which are required by [the spec](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md).
  51.      *
  52.      * @var array
  53.      */
  54.     public static $_required = [];
  56.     /**
  57.      * Specify the type of the property.
  58.      *
  59.      * Examples:
  60.      *   'name' => 'string' // a string
  61.      *   'required' => 'boolean', // true or false
  62.      *   'tags' => '[string]', // array containing strings
  63.      *   'in' => ["query", "header", "path", "formData", "body"] // must be one on these
  64.      *   'oneOf' => [Schema::class] // array of schema objects.
  65.      *
  66.      * @var array<string,string|array<string>>
  67.      */
  68.     public static $_types = [];
  70.     /**
  71.      * Declarative mapping of Annotation types to properties.
  72.      * Examples:
  73.      *   Info::clas => 'info', // Set @OA\Info annotation as the info property.
  74.      *   Parameter::clas => ['parameters'],  // Append @OA\Parameter annotations the parameters array.
  75.      *   PathItem::clas => ['paths', 'path'],  // Append @OA\PathItem annotations the paths array and use path as key.
  76.      *
  77.      * @var array<class-string<AbstractAnnotation>,string|array<string>>
  78.      */
  79.     public static $_nested = [];
  81.     /**
  82.      * Reverse mapping of $_nested with the allowed parent annotations.
  83.      *
  84.      * @var array<class-string<AbstractAnnotation>>
  85.      */
  86.     public static $_parents = [];
  88.     /**
  89.      * List of properties are blacklisted from the JSON output.
  90.      *
  91.      * @var array<string>
  92.      */
  93.     public static $_blacklist = ['_context', '_unmerged', '_analysis', 'attachables'];
  95.     public function __construct(array $properties)
  96.     {
  97.         if (isset($properties['_context'])) {
  98.             $this->_context = $properties['_context'];
  99.             unset($properties['_context']);
  100.         } elseif (Generator::$context) {
  101.             $this->_context = Generator::$context;
  102.         } else {
  103.             $this->_context = Context::detect(1);
  104.         }
  106.         if ($this->_context->is('annotations') === false) {
  107.             $this->_context->annotations = [];
  108.         }
  110.         $this->_context->annotations[] = $this;
  111.         $nestedContext = new Context(['nested' => $this], $this->_context);
  112.         foreach ($properties as $property => $value) {
  113.             if (property_exists($this, $property)) {
  114.                 $this->{$property} = $value;
  115.                 if (is_array($value)) {
  116.                     foreach ($value as $key => $annotation) {
  117.                         if ($annotation instanceof AbstractAnnotation) {
  118.                             $this->{$property}[$key] = $this->nested($annotation, $nestedContext);
  119.                         }
  120.                     }
  121.                 }
  122.             } elseif ($property !== 'value') {
  123.                 $this->{$property} = $value;
  124.             } elseif (is_array($value)) {
  125.                 $annotations = [];
  126.                 foreach ($value as $annotation) {
  127.                     if ($annotation instanceof AbstractAnnotation) {
  128.                         $annotations[] = $annotation;
  129.                     } else {
  130.                         $this->_context->logger->warning('Unexpected field in ' . $this->identity() . ' in ' . $this->_context);
  131.                     }
  132.                 }
  133.                 $this->merge($annotations);
  134.             } elseif (is_object($value)) {
  135.                 $this->merge([$value]);
  136.             } else {
  137.                 if (!Generator::isDefault($value)) {
  138.                     $this->_context->logger->warning('Unexpected parameter "' . $property . '" in ' . $this->identity());
  139.                 }
  140.             }
  141.         }
  143.         if ($this instanceof OpenApi) {
  144.             if ($this->_context->root()->version) {
  145.                 // override via `Generator::setVersion()`
  146.                 $this->openapi = $this->_context->root()->version;
  147.             } else {
  148.                 $this->_context->root()->version = $this->openapi;
  149.             }
  150.         }
  151.     }
  153.     public function __get(string $property)
  154.     {
  155.         $properties = get_object_vars($this);
  156.         $this->_context->logger->warning('Property "' . $property . '" doesn\'t exist in a ' . $this->identity() . ', existing properties: "' . implode('", "', array_keys($properties)) . '" in ' . $this->_context);
  157.     }
  159.     /**
  160.      * @param mixed $value
  161.      */
  162.     public function __set(string $property, $value): void
  163.     {
  164.         $fields = get_object_vars($this);
  165.         foreach (static::$_blacklist as $_property) {
  166.             unset($fields[$_property]);
  167.         }
  168.         $this->_context->logger->warning('Unexpected field "' . $property . '" for ' . $this->identity() . ', expecting "' . implode('", "', array_keys($fields)) . '" in ' . $this->_context);
  169.         $this->{$property} = $value;
  170.     }
  172.     /**
  173.      * Merge given annotations to their mapped properties configured in static::$_nested.
  174.      *
  175.      * Annotations that couldn't be merged are added to the _unmerged array.
  176.      *
  177.      * @param AbstractAnnotation[] $annotations
  178.      * @param bool                 $ignore      Ignore unmerged annotations
  179.      *
  180.      * @return AbstractAnnotation[] The unmerged annotations
  181.      */
  182.     public function merge(array $annotations, bool $ignore = false): array
  183.     {
  184.         $unmerged = [];
  185.         $nestedContext = new Context(['nested' => $this], $this->_context);
  187.         foreach ($annotations as $annotation) {
  188.             $mapped = false;
  189.             if ($details = $this->matchNested($annotation)) {
  190.                 $property = $details->value;
  191.                 if (is_array($property)) {
  192.                     $property = $property[0];
  193.                     if (Generator::isDefault($this->{$property})) {
  194.                         $this->{$property} = [];
  195.                     }
  196.                     $this->{$property}[] = $this->nested($annotation, $nestedContext);
  197.                     $mapped = true;
  198.                 } elseif (Generator::isDefault($this->{$property})) {
  199.                     // ignore duplicate nested if only one expected
  200.                     $this->{$property} = $this->nested($annotation, $nestedContext);
  201.                     $mapped = true;
  202.                 }
  203.             }
  204.             if (!$mapped) {
  205.                 $unmerged[] = $annotation;
  206.             }
  207.         }
  208.         if (!$ignore) {
  209.             foreach ($unmerged as $annotation) {
  210.                 $this->_unmerged[] = $this->nested($annotation, $nestedContext);
  211.             }
  212.         }
  214.         return $unmerged;
  215.     }
  217.     /**
  218.      * Merge the properties from the given object into this annotation.
  219.      * Prevents overwriting properties that are already configured.
  220.      *
  221.      * @param object $object
  222.      */
  223.     public function mergeProperties($object): void
  224.     {
  225.         $defaultValues = get_class_vars(get_class($this));
  226.         $currentValues = get_object_vars($this);
  227.         foreach ($object as $property => $value) {
  228.             if ($property === '_context') {
  229.                 continue;
  230.             }
  231.             if ($currentValues[$property] === $defaultValues[$property]) { // Overwrite default values
  232.                 $this->{$property} = $value;
  233.                 continue;
  234.             }
  235.             if ($property === '_unmerged') {
  236.                 $this->_unmerged = array_merge($this->_unmerged, $value);
  237.                 continue;
  238.             }
  239.             if ($currentValues[$property] !== $value) { // New value is not the same?
  240.                 if ($defaultValues[$property] === $value) { // but is the same as the default?
  241.                     continue; // Keep current, no notice
  242.                 }
  243.                 $identity = method_exists($object, 'identity') ? $object->identity() : get_class($object);
  244.                 $context1 = $this->_context;
  245.                 $context2 = property_exists($object, '_context') ? $object->_context : 'unknown';
  246.                 if (is_object($this->{$property}) && $this->{$property} instanceof AbstractAnnotation) {
  247.                     $context1 = $this->{$property}->_context;
  248.                 }
  249.                 $this->_context->logger->error('Multiple definitions for ' . $identity . '->' . $property . "\n     Using: " . $context1 . "\n  Skipping: " . $context2);
  250.             }
  251.         }
  252.     }
  254.     /**
  255.      * Generate the documentation in YAML format.
  256.      */
  257.     public function toYaml(?int $flags = null): string
  258.     {
  259.         if ($flags === null) {
  260.             $flags = Yaml::DUMP_OBJECT_AS_MAP ^ Yaml::DUMP_EMPTY_ARRAY_AS_SEQUENCE;
  261.         }
  263.         return Yaml::dump(json_decode($this->toJson(JSON_INVALID_UTF8_IGNORE)), 10, 2, $flags);
  264.     }
  266.     /**
  267.      * Generate the documentation in JSON format.
  268.      */
  269.     public function toJson(?int $flags = null): string
  270.     {
  271.         if ($flags === null) {
  272.             $flags = JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE | JSON_INVALID_UTF8_IGNORE;
  273.         }
  275.         return json_encode($this, $flags);
  276.     }
  278.     public function __debugInfo()
  279.     {
  280.         $properties = [];
  281.         foreach (get_object_vars($this) as $property => $value) {
  282.             if (!Generator::isDefault($value)) {
  283.                 $properties[$property] = $value;
  284.             }
  285.         }
  287.         return $properties;
  288.     }
  290.     /**
  291.      * @return mixed
  292.      */
  293.     #[\ReturnTypeWillChange]
  294.     public function jsonSerialize()
  295.     {
  296.         $data = new \stdClass();
  298.         // Strip undefined values.
  299.         foreach (get_object_vars($this) as $property => $value) {
  300.             if (!Generator::isDefault($value)) {
  301.                 $data->{$property} = $value;
  302.             }
  303.         }
  305.         // Strip properties that are for internal (swagger-php) use.
  306.         foreach (static::$_blacklist as $property) {
  307.             unset($data->{$property});
  308.         }
  310.         // Correct empty array to empty objects.
  311.         foreach (static::$_types as $property => $type) {
  312.             if ($type === 'object' && is_array($data->{$property}) && empty($data->{$property})) {
  313.                 $data->{$property} = new \stdClass();
  314.             }
  315.         }
  317.         // Inject vendor properties.
  318.         unset($data->x);
  319.         if (is_array($this->x)) {
  320.             foreach ($this->x as $property => $value) {
  321.                 $prefixed = 'x-' . $property;
  322.                 $data->{$prefixed} = $value;
  323.             }
  324.         }
  326.         // Map nested keys
  327.         foreach (static::$_nested as $nested) {
  328.             if (is_string($nested) || count($nested) === 1) {
  329.                 continue;
  330.             }
  331.             $property = $nested[0];
  332.             if (Generator::isDefault($this->{$property})) {
  333.                 continue;
  334.             }
  335.             $keyField = $nested[1];
  336.             $object = new \stdClass();
  337.             foreach ($this->{$property} as $key => $item) {
  338.                 if (is_numeric($key) === false && is_array($item)) {
  339.                     $object->{$key} = $item;
  340.                 } else {
  341.                     $key = $item->{$keyField};
  342.                     if (!Generator::isDefault($key) && empty($object->{$key})) {
  343.                         if ($item instanceof \JsonSerializable) {
  344.                             $object->{$key} = $item->jsonSerialize();
  345.                         } else {
  346.                             $object->{$key} = $item;
  347.                         }
  348.                         unset($object->{$key}->{$keyField});
  349.                     }
  350.                 }
  351.             }
  352.             $data->{$property} = $object;
  353.         }
  355.         // $ref
  356.         if (isset($data->ref)) {
  357.             // Only specific https://github.com/OAI/OpenAPI-Specification/blob/3.1.0/versions/3.1.0.md#reference-object
  358.             $ref = ['$ref' => $data->ref];
  359.             $defaultValues = get_class_vars(get_class($this));
  360.             if ($this->_context->version === OpenApi::VERSION_3_1_0) {
  361.                 foreach (['summary', 'description'] as $prop) {
  362.                     if (property_exists($this, $prop)) {
  363.                         if ($this->{$prop} !== $defaultValues[$prop]) {
  364.                             $ref[$prop] = $data->{$prop};
  365.                         }
  366.                     }
  367.                 }
  368.             }
  369.             if (property_exists($this, 'nullable') && $this->nullable === true) {
  370.                 $ref = ['oneOf' => [$ref]];
  371.                 if ($this->_context->version == OpenApi::VERSION_3_1_0) {
  372.                     $ref['oneOf'][] = ['type' => 'null'];
  373.                 } else {
  374.                     $ref['nullable'] = $data->nullable;
  375.                 }
  376.                 unset($data->nullable);
  377.             }
  378.             $data = (object) $ref;
  379.         }
  381.         if ($this->_context->version === OpenApi::VERSION_3_1_0) {
  382.             if (isset($data->nullable)) {
  383.                 if (true === $data->nullable) {
  384.                     $data->type = (array) $data->type;
  385.                     $data->type[] = 'null';
  386.                 }
  387.                 unset($data->nullable);
  388.             }
  389.         }
  391.         return $data;
  392.     }
  394.     /**
  395.      * Validate annotation tree, and log notices & warnings.
  396.      *
  397.      * @param array  $stack   the path of annotations above this annotation in the tree
  398.      * @param array  $skip    (prevent stack overflow, when traversing an infinite dependency graph)
  399.      * @param string $ref     Current ref path?
  400.      * @param object $context a free-form context contains
  401.      */
  402.     public function validate(array $stack = [], array $skip = [], string $ref = '', $context = null): bool
  403.     {
  404.         if (in_array($this, $skip, true)) {
  405.             return true;
  406.         }
  408.         $valid = true;
  410.         // Report orphaned annotations
  411.         foreach ($this->_unmerged as $annotation) {
  412.             if (!is_object($annotation)) {
  413.                 $this->_context->logger->warning('Unexpected type: "' . gettype($annotation) . '" in ' . $this->identity() . '->_unmerged, expecting a Annotation object');
  414.                 break;
  415.             }
  417.             /** @var class-string<AbstractAnnotation> $class */
  418.             $class = get_class($annotation);
  419.             if ($details = $this->matchNested($annotation)) {
  420.                 $property = $details->value;
  421.                 if (is_array($property)) {
  422.                     $this->_context->logger->warning('Only one ' . Util::shorten(get_class($annotation)) . '() allowed for ' . $this->identity() . ' multiple found, skipped: ' . $annotation->_context);
  423.                 } else {
  424.                     $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);
  425.                 }
  426.             } elseif ($annotation instanceof AbstractAnnotation) {
  427.                 $message = 'Unexpected ' . $annotation->identity();
  428.                 if ($class::$_parents) {
  429.                     $message .= ', expected to be inside ' . implode(', ', Util::shorten($class::$_parents));
  430.                 }
  431.                 $this->_context->logger->warning($message . ' in ' . $annotation->_context);
  432.             }
  433.             $valid = false;
  434.         }
  436.         // Report conflicting key
  437.         foreach (static::$_nested as $annotationClass => $nested) {
  438.             if (is_string($nested) || count($nested) === 1) {
  439.                 continue;
  440.             }
  441.             $property = $nested[0];
  442.             if (Generator::isDefault($this->{$property})) {
  443.                 continue;
  444.             }
  445.             $keys = [];
  446.             $keyField = $nested[1];
  447.             foreach ($this->{$property} as $key => $item) {
  448.                 if (is_array($item) && is_numeric($key) === false) {
  449.                     $this->_context->logger->warning($this->identity() . '->' . $property . ' is an object literal, use nested ' . Util::shorten($annotationClass) . '() annotation(s) in ' . $this->_context);
  450.                     $keys[$key] = $item;
  451.                 } elseif (Generator::isDefault($item->{$keyField})) {
  452.                     $this->_context->logger->error($item->identity() . ' is missing key-field: "' . $keyField . '" in ' . $item->_context);
  453.                 } elseif (isset($keys[$item->{$keyField}])) {
  454.                     $this->_context->logger->error('Multiple ' . $item->_identity([]) . ' with the same ' . $keyField . '="' . $item->{$keyField} . "\":\n  " . $item->_context . "\n  " . $keys[$item->{$keyField}]->_context);
  455.                 } else {
  456.                     $keys[$item->{$keyField}] = $item;
  457.                 }
  458.             }
  459.         }
  461.         if (property_exists($this, 'ref') && !Generator::isDefault($this->ref) && is_string($this->ref)) {
  462.             if (substr($this->ref, 0, 2) === '#/' && count($stack) > 0 && $stack[0] instanceof OpenApi) {
  463.                 // Internal reference
  464.                 try {
  465.                     $stack[0]->ref($this->ref);
  466.                 } catch (\Exception $e) {
  467.                     $this->_context->logger->warning($e->getMessage() . ' for ' . $this->identity() . ' in ' . $this->_context, ['exception' => $e]);
  468.                 }
  469.             }
  470.         } else {
  471.             // Report missing required fields (when not a $ref)
  472.             foreach (static::$_required as $property) {
  473.                 if (Generator::isDefault($this->{$property})) {
  474.                     $message = 'Missing required field "' . $property . '" for ' . $this->identity() . ' in ' . $this->_context;
  475.                     foreach (static::$_nested as $class => $nested) {
  476.                         $nestedProperty = is_array($nested) ? $nested[0] : $nested;
  477.                         if ($property === $nestedProperty) {
  478.                             if ($this instanceof OpenApi) {
  479.                                 $message = 'Required ' . Util::shorten($class) . '() not found';
  480.                             } elseif (is_array($nested)) {
  481.                                 $message = $this->identity() . ' requires at least one ' . Util::shorten($class) . '() in ' . $this->_context;
  482.                             } else {
  483.                                 $message = $this->identity() . ' requires a ' . Util::shorten($class) . '() in ' . $this->_context;
  484.                             }
  485.                             break;
  486.                         }
  487.                     }
  488.                     $this->_context->logger->warning($message);
  489.                 }
  490.             }
  491.         }
  493.         // Report invalid types
  494.         foreach (static::$_types as $property => $type) {
  495.             $value = $this->{$property};
  496.             if (Generator::isDefault($value) || $value === null) {
  497.                 continue;
  498.             }
  499.             if (is_string($type)) {
  500.                 if ($this->validateType($type, $value) === false) {
  501.                     $valid = false;
  502.                     $this->_context->logger->warning($this->identity() . '->' . $property . ' is a "' . gettype($value) . '", expecting a "' . $type . '" in ' . $this->_context);
  503.                 }
  504.             } elseif (is_array($type)) { // enum?
  505.                 if (in_array($value, $type) === false) {
  506.                     $this->_context->logger->warning($this->identity() . '->' . $property . ' "' . $value . '" is invalid, expecting "' . implode('", "', $type) . '" in ' . $this->_context);
  507.                 }
  508.             } else {
  509.                 throw new \Exception('Invalid ' . get_class($this) . '::$_types[' . $property . ']');
  510.             }
  511.         }
  512.         $stack[] = $this;
  514.         return self::_validate($this, $stack, $skip, $ref, $context) ? $valid : false;
  515.     }
  517.     /**
  518.      * Recursively validate all annotation properties.
  519.      *
  520.      * @param array|object $fields
  521.      */
  522.     private static function _validate($fields, array $stack, array $skip, string $baseRef, ?object $context): bool
  523.     {
  524.         $valid = true;
  525.         $blacklist = [];
  526.         if (is_object($fields)) {
  527.             if (in_array($fields, $skip, true)) {
  528.                 return true;
  529.             }
  530.             $skip[] = $fields;
  531.             $blacklist = property_exists($fields, '_blacklist') ? $fields::$_blacklist : [];
  532.         }
  534.         foreach ($fields as $field => $value) {
  535.             if ($value === null || is_scalar($value) || in_array($field, $blacklist)) {
  536.                 continue;
  537.             }
  538.             $ref = $baseRef !== '' ? $baseRef . '/' . urlencode((string) $field) : urlencode((string) $field);
  539.             if (is_object($value)) {
  540.                 if (method_exists($value, 'validate')) {
  541.                     if (!$value->validate($stack, $skip, $ref, $context)) {
  542.                         $valid = false;
  543.                     }
  544.                 } elseif (!self::_validate($value, $stack, $skip, $ref, $context)) {
  545.                     $valid = false;
  546.                 }
  547.             } elseif (is_array($value) && !self::_validate($value, $stack, $skip, $ref, $context)) {
  548.                 $valid = false;
  549.             }
  550.         }
  552.         return $valid;
  553.     }
  555.     /**
  556.      * Return a identity for easy debugging.
  557.      * Example: "@OA\Get(path="/pets")".
  558.      */
  559.     public function identity(): string
  560.     {
  561.         $class = get_class($this);
  562.         $properties = [];
  563.         /** @var class-string<AbstractAnnotation> $parent */
  564.         foreach (static::$_parents as $parent) {
  565.             foreach ($parent::$_nested as $annotationClass => $entry) {
  566.                 if ($annotationClass === $class && is_array($entry) && !Generator::isDefault($this->{$entry[1]})) {
  567.                     $properties[] = $entry[1];
  568.                     break 2;
  569.                 }
  570.             }
  571.         }
  573.         return $this->_identity($properties);
  574.     }
  576.     /**
  577.      * Check if `$other` can be nested and if so return details about where/how.
  578.      *
  579.      * @param AbstractAnnotation $other the other annotation
  580.      *
  581.      * @return null|object key/value object or `null`
  582.      */
  583.     public function matchNested($other)
  584.     {
  585.         if ($other instanceof AbstractAnnotation && array_key_exists($root = $other->getRoot(), static::$_nested)) {
  586.             return (object) ['key' => $root, 'value' => static::$_nested[$root]];
  587.         }
  589.         return null;
  590.     }
  592.     /**
  593.      * Get the root annotation.
  594.      *
  595.      * This is used for resolving type equality and nesting rules to allow those rules to also work for custom,
  596.      * derived annotation classes.
  597.      *
  598.      * @return class-string the root annotation class in the `OpenApi\\Annotations` namespace
  599.      */
  600.     public function getRoot(): string
  601.     {
  602.         $class = get_class($this);
  604.         do {
  605.             if (0 === strpos($class, 'OpenApi\\Annotations\\')) {
  606.                 break;
  607.             }
  608.         } while ($class = get_parent_class($class));
  610.         return $class;
  611.     }
  613.     /**
  614.      * Match the annotation root.
  615.      *
  616.      * @param class-string $rootClass the root class to match
  617.      */
  618.     public function isRoot(string $rootClass): bool
  619.     {
  620.         return $this->getRoot() == $rootClass;
  621.     }
  623.     /**
  624.      * Helper for generating the identity().
  625.      */
  626.     protected function _identity(array $properties): string
  627.     {
  628.         $fields = [];
  629.         foreach ($properties as $property) {
  630.             $value = $this->{$property};
  631.             if ($value !== null && !Generator::isDefault($value)) {
  632.                 $fields[] = $property . '=' . (is_string($value) ? '"' . $value . '"' : $value);
  633.             }
  634.         }
  636.         return Util::shorten(get_class($this)) . '(' . implode(',', $fields) . ')';
  637.     }
  639.     /**
  640.      * Validates the matching of the property value to a annotation type.
  641.      *
  642.      * @param string $type  The annotations property type
  643.      * @param mixed  $value The property value
  644.      */
  645.     private function validateType(string $type, $value): bool
  646.     {
  647.         if (substr($type, 0, 1) === '[' && substr($type, -1) === ']') { // Array of a specified type?
  648.             if ($this->validateType('array', $value) === false) {
  649.                 return false;
  650.             }
  651.             $itemType = substr($type, 1, -1);
  652.             foreach ($value as $i => $item) {
  653.                 if ($this->validateType($itemType, $item) === false) {
  654.                     return false;
  655.                 }
  656.             }
  658.             return true;
  659.         }
  661.         if (is_subclass_of($type, AbstractAnnotation::class)) {
  662.             $type = 'object';
  663.         }
  665.         return $this->validateDefaultTypes($type, $value);
  666.     }
  668.     /**
  669.      * Validates default Open Api types.
  670.      *
  671.      * @param string $type  The property type
  672.      * @param mixed  $value The value to validate
  673.      */
  674.     private function validateDefaultTypes(string $type, $value): bool
  675.     {
  676.         switch ($type) {
  677.             case 'string':
  678.                 return is_string($value);
  679.             case 'boolean':
  680.                 return is_bool($value);
  681.             case 'integer':
  682.                 return is_int($value);
  683.             case 'number':
  684.                 return is_numeric($value);
  685.             case 'object':
  686.                 return is_object($value);
  687.             case 'array':
  688.                 return $this->validateArrayType($value);
  689.             case 'scheme':
  690.                 return in_array($value, ['http', 'https', 'ws', 'wss'], true);
  691.             default:
  692.                 throw new \Exception('Invalid type "' . $type . '"');
  693.         }
  694.     }
  696.     /**
  697.      * Validate array type.
  698.      *
  699.      * @param mixed $value
  700.      */
  701.     private function validateArrayType($value): bool
  702.     {
  703.         if (is_array($value) === false) {
  704.             return false;
  705.         }
  706.         $count = 0;
  707.         foreach ($value as $i => $item) {
  708.             // not a array, but a hash/map
  709.             if ($count !== $i) {
  710.                 return false;
  711.             }
  712.             $count++;
  713.         }
  715.         return true;
  716.     }
  718.     /**
  719.      * Wrap the context with a reference to the annotation it is nested in.
  720.      *
  721.      * @param AbstractAnnotation $annotation
  722.      *
  723.      * @return AbstractAnnotation
  724.      */
  725.     protected function nested(AbstractAnnotation $annotation, Context $nestedContext)
  726.     {
  727.         if (property_exists($annotation, '_context') && $annotation->_context === $this->_context) {
  728.             $annotation->_context = $nestedContext;
  729.         }
  731.         return $annotation;
  732.     }
  734.     protected function combine(...$args): array
  735.     {
  736.         $combined = [];
  737.         foreach ($args as $arg) {
  738.             if (is_array($arg)) {
  739.                 $combined = array_merge($combined, $arg);
  740.             } else {
  741.                 $combined[] = $arg;
  742.             }
  743.         }
  745.         return array_filter($combined, function ($value) {
  746.             return !Generator::isDefault($value) && $value !== null;
  747.         });
  748.     }
  749. }