Debian Codegraph @

vendor/zircote/swagger-php/src/Processors/ExpandEnums.php

raw
1 <?php declare(strict_types=1);
2
3 /**
4 * @license Apache 2.0
5 */
6
7 namespace OpenApi\Processors;
8
9 use OpenApi\Analysis;
10 use OpenApi\Annotations as OA;
11 use OpenApi\Generator;
12 use OpenApi\GeneratorAwareInterface;
13 use OpenApi\GeneratorAwareTrait;
14 use OpenApi\OpenApiException;
15
16 /**
17 * Expands PHP enums.
18 *
19 * Determines <code>schema</code>, <code>enum</code> and <code>type</code>.
20 */
21 class ExpandEnums implements GeneratorAwareInterface
22 {
23 use GeneratorAwareTrait;
24
25 protected ?string $enumNames;
26
27 public function __construct(?string $enumNames = null)
28 {
29 $this->enumNames = $enumNames;
30 }
31
32 public function getEnumNames(): ?string
33 {
34 return $this->enumNames;
35 }
36
37 /**
38 * Specifies the name of the extension variable where backed enum names will be stored.
39 * Set to <code>null</code> to avoid writing backed enum names.
40 *
41 * Example:
42 * <code>->setEnumNames('enumNames')</code> yields:
43 * ```yaml
44 * x-enumNames:
45 * - NAME1
46 * - NAME2
47 * ```
48 */
49 public function setEnumNames(?string $enumNames = null): void
50 {
51 $this->enumNames = $enumNames;
52 }
53
54 public function __invoke(Analysis $analysis): void
55 {
56 if (!class_exists('\\ReflectionEnum')) {
57 return;
58 }
59
60 $this->expandContextEnum($analysis);
61 $this->expandSchemaEnum($analysis);
62 }
63
64 protected function expandContextEnum(Analysis $analysis): void
65 {
66 $schemas = $analysis->getAnnotationsOfType(OA\Schema::class, true);
67
68 foreach ($schemas as $schema) {
69 if ($schema->_context->is('enum')) {
70 $re = new \ReflectionEnum($schema->_context->fullyQualifiedName($schema->_context->enum) ?? '');
71 $schema->schema = Generator::isDefault($schema->schema) ? $re->getShortName() : $schema->schema;
72
73 $schemaType = $schema->type;
74 $enumType = null;
75 if ($re->isBacked()) {
76 $enumType = $re->getBackingType()->getName();
77 }
78
79 // no (or invalid) schema type means name
80 $useName = Generator::isDefault($schemaType) || ($enumType && $this->generator->getTypeResolver()->native2spec($enumType) != $schemaType);
81
82 $schema->enum = array_map(static fn (\ReflectionEnumUnitCase $case): int|string => ($useName || !($case instanceof \ReflectionEnumBackedCase)) ? $case->name : $case->getBackingValue(), $re->getCases());
83
84 if ($this->enumNames !== null && !$useName) {
85 $schemaX = Generator::isDefault($schema->x) ? [] : $schema->x;
86 $schemaX[$this->enumNames] = array_map(static fn (\ReflectionEnumUnitCase $case): string => $case->name, $re->getCases());
87
88 $schema->x = $schemaX;
89 }
90
91 $schema->type = $useName ? 'string' : $enumType;
92
93 $this->generator->getTypeResolver()->mapNativeType($schema, $schemaType);
94 }
95 }
96 }
97
98 protected function expandSchemaEnum(Analysis $analysis): void
99 {
100 $schemas = $analysis->getAnnotationsOfType([OA\Schema::class, OA\ServerVariable::class]);
101
102 foreach ($schemas as $schema) {
103 if (Generator::isDefault($schema->enum)) {
104 continue;
105 }
106
107 if (is_string($schema->enum)) {
108 // might be enum class-string
109 if (is_a($schema->enum, \UnitEnum::class, true)) {
110 $cases = $schema->enum::cases();
111 } else {
112 throw new OpenApiException("Unexpected enum value, requires specifying the Enum class string: $schema->enum");
113 }
114 } else {
115 // might be an array of \UnitEnum::class, string, int, etc...
116 assert(is_array($schema->enum));
117
118 $cases = [];
119
120 // transform \UnitEnum into individual cases
121 /** @var string|class-string<\UnitEnum> $enum */
122 foreach ($schema->enum as $enum) {
123 if (is_string($enum) && function_exists('enum_exists') && enum_exists($enum)) {
124 foreach ($enum::cases() as $case) {
125 $cases[] = $case;
126 }
127 } else {
128 $cases[] = $enum;
129 }
130 }
131 }
132
133 $enums = [];
134 foreach ($cases as $enum) {
135 $enums[] = is_a($enum, \UnitEnum::class) ? $enum->value ?? $enum->name : $enum;
136 }
137
138 $schema->enum = $enums;
139 }
140 }
141 }