$className */ protected static function isValidAnnotationClass(string $className): bool { return in_array($className, self::$VALID_ANNOTATIONS); } /** * Deserialize a string. * * @param class-string $className */ public function deserialize(string $jsonString, string $className, ?Context $context = null): OA\AbstractAnnotation { if (!static::isValidAnnotationClass($className)) { throw new OpenApiException($className . ' is not defined in OpenApi PHP Annotations'); } return $this->doDeserialize(json_decode($jsonString), $className, $context ?? new Context(['generated' => true])); } /** * Deserialize a file. * * @param class-string $className */ public function deserializeFile(string $filename, string $format = 'json', string $className = OA\OpenApi::class, ?Context $context = null): OA\AbstractAnnotation { if (!static::isValidAnnotationClass($className)) { throw new OpenApiException($className . ' is not a valid OpenApi PHP Annotations'); } $contents = file_get_contents($filename); $ext = pathinfo($filename, PATHINFO_EXTENSION); if ('yaml' === $format || in_array($ext, ['yml', 'yaml'], strict: true)) { $contents = json_encode(Yaml::parse($contents)); } return $this->doDeserialize(json_decode($contents), $className, $context ?? new Context(['generated' => true])); } /** * Do deserialization. * * @param class-string $className */ protected function doDeserialize(\stdClass $c, string $className, Context $context): OA\AbstractAnnotation { $annotation = new $className(['_context' => $context]); foreach ((array) $c as $property => $value) { if ($property === '$ref') { $property = 'ref'; } if (str_starts_with((string) $property, 'x-')) { if (Generator::isDefault($annotation->x)) { $annotation->x = []; } $custom = substr((string) $property, 2); $annotation->x[$custom] = $value; } else { $annotation->{$property} = $this->doDeserializeProperty($annotation, $property, $value, $context); } } if ($annotation instanceof OA\OpenApi) { $context->root()->version = $annotation->openapi; } return $annotation; } /** * Deserialize the annotation's property. */ protected function doDeserializeProperty(OA\AbstractAnnotation $annotation, string $property, $value, Context $context) { // property is primitive type if (array_key_exists($property, $annotation::$_types)) { return $this->doDeserializeBaseProperty($annotation::$_types[$property], $value, $context); } // property is embedded annotation // note: this does not support custom nested annotation classes foreach ($annotation::$_nested as $nestedClass => $declaration) { if (is_string($declaration)) { // property is an annotation if ($declaration === $property) { if (is_object($value)) { return $this->doDeserialize($value, $nestedClass, $context); } else { return $value; } } } elseif (count($declaration) === 1 && $declaration[0] === $property) { // property is an annotation array $annotationArr = []; foreach ($value as $v) { $annotationArr[] = $this->doDeserialize($v, $nestedClass, $context); } return $annotationArr; } elseif (count($declaration) === 2 && $declaration[0] === $property) { $key = $declaration[1]; $annotationHash = []; foreach ($value as $k => $v) { $annotation = $this->doDeserialize($v, $nestedClass, $context); $annotation->{$key} = $k; $annotationHash[$k] = $annotation; } return $annotationHash; } } return $value; } /** * Deserialize base annotation property. * * @param array|string $type The property type * @param mixed $value The value to deserialization * * @return array|OA\AbstractAnnotation */ protected function doDeserializeBaseProperty($type, mixed $value, Context $context) { $isAnnotationClass = is_string($type) && is_subclass_of(trim($type, '[]'), OA\AbstractAnnotation::class); if ($isAnnotationClass) { $isArray = str_starts_with($type, '[') && str_ends_with($type, ']'); if ($isArray) { $annotationArr = []; $class = trim($type, '[]'); foreach ($value as $v) { $annotationArr[] = $this->doDeserialize($v, $class, $context); } return $annotationArr; } return $this->doDeserialize($value, $type, $context); } return $value; } }