Debian Codegraph @

vendor/zircote/swagger-php/src/Analysis.php

raw
1 <?php declare(strict_types=1);
2
3 /**
4 * @license Apache 2.0
5 */
6
7 namespace OpenApi;
8
9 use OpenApi\Annotations as OA;
10
11 /**
12 * Result of the analyser.
13 *
14 * Pretends to be an array of annotations but also contains detected classes and helper functions for the processors.
15 */
16 class Analysis
17 {
18 /** @var \SplObjectStorage<OA\AbstractAnnotation, Context> */
19 public \SplObjectStorage $annotations;
20
21 /**
22 * Class definitions.
23 */
24 public array $classes = [];
25
26 /**
27 * Interface definitions.
28 */
29 public array $interfaces = [];
30
31 /**
32 * Trait definitions.
33 */
34 public array $traits = [];
35
36 /**
37 * Enum definitions.
38 */
39 public array $enums = [];
40
41 /**
42 * The target OpenApi annotation.
43 */
44 public ?OA\OpenApi $openapi = null;
45
46 public ?Context $context = null;
47
48 /**
49 * @param list<OA\AbstractAnnotation> $annotations
50 */
51 public function __construct(array $annotations = [], ?Context $context = null)
52 {
53 $this->annotations = new \SplObjectStorage();
54 $this->context = $context;
55
56 $this->addAnnotations($annotations, $context);
57 }
58
59 public function addAnnotation(OA\AbstractAnnotation $annotation, Context $context): void
60 {
61 if ($this->annotations->offsetExists($annotation)) {
62 return;
63 }
64
65 $context->ensureRoot($this->context);
66
67 if ($annotation instanceof OA\OpenApi) {
68 $this->openapi = $this->openapi ?: $annotation;
69 } else {
70 if ($context->is('annotations') === false) {
71 $context->annotations = [];
72 }
73
74 if (in_array($annotation, $context->annotations, strict: true) === false) {
75 $context->annotations[] = $annotation;
76 }
77 }
78
79 $this->annotations->offsetSet($annotation, $context);
80
81 foreach (get_object_vars($annotation) as $property => $value) {
82 if (in_array($property, $annotation::$_blacklist)) {
83 if ($property === '_unmerged') {
84 foreach ($value as $item) {
85 $this->addAnnotation($item, $context);
86 }
87 }
88 } elseif (is_array($value)) {
89 foreach ($value as $item) {
90 if ($item instanceof OA\AbstractAnnotation) {
91 $this->addAnnotation($item, $context);
92 }
93 }
94 } elseif ($value instanceof OA\AbstractAnnotation) {
95 $this->addAnnotation($value, $context);
96 }
97 }
98 }
99
100 public function removeAnnotation(OA\AbstractAnnotation $annotation): void
101 {
102 if ($this->annotations->offsetExists($annotation)) {
103 $context = $this->annotations->offsetGet($annotation);
104 $this->annotations->offsetUnset($annotation);
105
106 if ($context->is('annotations') !== false) {
107 $index = array_search($annotation, $context->annotations, true);
108 if ($index !== false) {
109 array_splice($context->annotations, $index, 1);
110 }
111 }
112 }
113 }
114
115 /**
116 * @param list<OA\AbstractAnnotation> $annotations
117 */
118 public function addAnnotations(array $annotations, Context $context): void
119 {
120 foreach ($annotations as $annotation) {
121 $this->addAnnotation($annotation, $context);
122 }
123 }
124
125 /**
126 * Merge annotations into a parent and register any new ones in the analysis.
127 *
128 * Combines the tree-structural operation (AbstractAnnotation::merge) with
129 * registry registration (addAnnotation) so callers don't need to handle
130 * both separately.
131 *
132 * @param list<OA\AbstractAnnotation> $annotations
133 * @param bool $ignore Ignore unmerged annotations
134 *
135 * @return list<OA\AbstractAnnotation> The unmerged annotations
136 */
137 public function mergeAnnotations(OA\AbstractAnnotation $parent, array $annotations, bool $ignore = false): array
138 {
139 $unmerged = $parent->merge($annotations, $ignore);
140
141 foreach ($annotations as $annotation) {
142 if ($annotation instanceof OA\AbstractAnnotation) {
143 $this->addAnnotation($annotation, $annotation->_context);
144 }
145 }
146
147 return $unmerged;
148 }
149
150 public function addClassDefinition(array $definition): void
151 {
152 $class = $definition['context']->fullyQualifiedName($definition['class']);
153 $this->classes[$class] = $definition;
154 }
155
156 public function addInterfaceDefinition(array $definition): void
157 {
158 $interface = $definition['context']->fullyQualifiedName($definition['interface']);
159 $this->interfaces[$interface] = $definition;
160 }
161
162 public function addTraitDefinition(array $definition): void
163 {
164 $trait = $definition['context']->fullyQualifiedName($definition['trait']);
165 $this->traits[$trait] = $definition;
166 }
167
168 public function addEnumDefinition(array $definition): void
169 {
170 $enum = $definition['context']->fullyQualifiedName($definition['enum']);
171 $this->enums[$enum] = $definition;
172 }
173
174 public function addAnalysis(Analysis $analysis): void
175 {
176 foreach ($analysis->annotations as $annotation) {
177 $this->addAnnotation($annotation, $analysis->annotations[$annotation]);
178 }
179 $this->classes = array_merge($this->classes, $analysis->classes);
180 $this->interfaces = array_merge($this->interfaces, $analysis->interfaces);
181 $this->traits = array_merge($this->traits, $analysis->traits);
182 $this->enums = array_merge($this->enums, $analysis->enums);
183 if (!$this->openapi instanceof OA\OpenApi && $analysis->openapi instanceof OA\OpenApi) {
184 $this->openapi = $analysis->openapi;
185 }
186 }
187
188 /**
189 * Get all subclasses of the given parent class.
190 *
191 * @param class-string $parent the parent class
192 *
193 * @return array map of class => definition pairs of sub-classes
194 */
195 public function getSubClasses(string $parent): array
196 {
197 $definitions = [];
198 foreach ($this->classes as $class => $classDefinition) {
199 if ($classDefinition['extends'] === $parent) {
200 $definitions[$class] = $classDefinition;
201 $definitions = array_merge($definitions, $this->getSubClasses($class));
202 }
203 }
204
205 return $definitions;
206 }
207
208 /**
209 * Get a list of all super classes for the given class.
210 *
211 * @param class-string|null $class the class name
212 * @param bool $direct flag to find only the actual class parents
213 *
214 * @return array map of class => definition pairs of parent classes
215 */
216 public function getSuperClasses(?string $class, bool $direct = false): array
217 {
218 $classDefinition = $this->classes[$class ?? ''] ?? null;
219 if (!$classDefinition || empty($classDefinition['extends'])) {
220 // unknown class, or no inheritance
221 return [];
222 }
223
224 $extends = $classDefinition['extends'];
225 $extendsDefinition = $this->classes[$extends] ?? null;
226 if (!$extendsDefinition) {
227 return [];
228 }
229
230 $parentDetails = [$extends => $extendsDefinition];
231
232 if ($direct) {
233 return $parentDetails;
234 }
235
236 return array_merge($parentDetails, $this->getSuperClasses($extends));
237 }
238
239 /**
240 * Get the list of interfaces used by the given class or by classes which it extends.
241 *
242 * @param class-string|null $class the class name
243 * @param bool $direct flag to find only the actual class interfaces
244 *
245 * @return array map of class => definition pairs of interfaces
246 */
247 public function getInterfacesOfClass(?string $class, bool $direct = false): array
248 {
249 $classes = $direct ? [] : array_keys($this->getSuperClasses($class));
250 // add self
251 $classes[] = $class;
252
253 $definitions = [];
254 foreach ($classes as $clazz) {
255 if (isset($this->classes[$clazz])) {
256 $definition = $this->classes[$clazz];
257 if (isset($definition['implements'])) {
258 foreach ($definition['implements'] as $interface) {
259 if (array_key_exists($interface, $this->interfaces)) {
260 $definitions[$interface] = $this->interfaces[$interface];
261 }
262 }
263 }
264 }
265 }
266
267 if (!$direct) {
268 // expand recursively for interfaces extending other interfaces
269 $collect = function ($interfaces, $cb) use (&$definitions): void {
270 foreach ($interfaces as $interface) {
271 if (isset($this->interfaces[$interface]['extends'])) {
272 $cb($this->interfaces[$interface]['extends'], $cb);
273 foreach ($this->interfaces[$interface]['extends'] as $fqdn) {
274 $definitions[$fqdn] = $this->interfaces[$fqdn];
275 }
276 }
277 }
278 };
279 $collect(array_keys($definitions), $collect);
280 }
281
282 return $definitions;
283 }
284
285 /**
286 * Get the list of traits used by the given class/trait or by classes which it extends.
287 *
288 * @param string|null $source the source name
289 * @param bool $direct flag to find only the actual class traits
290 *
291 * @return array map of class => definition pairs of traits
292 */
293 public function getTraitsOfClass(?string $source, bool $direct = false): array
294 {
295 $sources = $direct ? [] : array_keys($this->getSuperClasses($source));
296 // add self
297 $sources[] = $source;
298
299 $definitions = [];
300 foreach ($sources as $sourze) {
301 if (isset($this->classes[$sourze]) || isset($this->traits[$sourze])) {
302 $definition = $this->classes[$sourze] ?? $this->traits[$sourze];
303 if (isset($definition['traits'])) {
304 foreach ($definition['traits'] as $trait) {
305 if (array_key_exists($trait, $this->traits)) {
306 $definitions[$trait] = $this->traits[$trait];
307 }
308 }
309 }
310 }
311 }
312
313 if (!$direct) {
314 // expand recursively for traits using other traits
315 $collect = function ($traits, $cb) use (&$definitions): void {
316 foreach ($traits as $trait) {
317 if (isset($this->traits[$trait]['traits'])) {
318 $cb($this->traits[$trait]['traits'], $cb);
319 foreach ($this->traits[$trait]['traits'] as $fqdn) {
320 $definitions[$fqdn] = $this->traits[$fqdn];
321 }
322 }
323 }
324 };
325 $collect(array_keys($definitions), $collect);
326 }
327
328 return $definitions;
329 }
330
331 /**
332 * @template T extends OA\AbstractAnnotation
333 *
334 * @param class-string<T>|list<class-string<T>> $classes one or more class names
335 * @param bool $strict in non-strict mode child classes are also detected
336 *
337 * @return list<T>
338 */
339 public function getAnnotationsOfType($classes, bool $strict = false): array
340 {
341 $unique = new \SplObjectStorage();
342 $annotations = [];
343
344 foreach ((array) $classes as $class) {
345 /** @var OA\AbstractAnnotation $annotation */
346 foreach ($this->annotations as $annotation) {
347 if ($annotation instanceof $class && (!$strict || ($annotation->isRoot($class) && !$unique->offsetExists($annotation)))) {
348 $unique->offsetSet($annotation);
349 $annotations[] = $annotation;
350 }
351 }
352 }
353
354 return $annotations;
355 }
356
357 /**
358 * @template T of OA\AbstractAnnotation
359 *
360 * @param string $fqdn the source class/interface/trait
361 * @param class-string<T> $sourceClass
362 * @return T|null
363 */
364 public function getAnnotationForSource(string $fqdn, string $sourceClass = OA\Schema::class): ?OA\AbstractAnnotation
365 {
366 $fqdn = '\\' . ltrim($fqdn, '\\');
367
368 foreach ([$this->classes, $this->interfaces, $this->traits, $this->enums] as $definitions) {
369 if (array_key_exists($fqdn, $definitions)) {
370 $definition = $definitions[$fqdn];
371 if (is_iterable($definition['context']->annotations)) {
372 /** @var OA\AbstractAnnotation $annotation */
373 foreach (array_reverse($definition['context']->annotations) as $annotation) {
374 if ($annotation instanceof $sourceClass && $annotation->isRoot($sourceClass) && !$annotation->_context->is('generated')) {
375 return $annotation;
376 }
377 }
378 }
379 }
380 }
381
382 return null;
383 }
384
385 /**
386 * Build an analysis with only the annotations that are merged into the OpenAPI annotation.
387 */
388 public function merged(): Analysis
389 {
390 if (!$this->openapi instanceof OA\OpenApi) {
391 throw new OpenApiException('No openapi target set. Run the MergeIntoOpenApi processor');
392 }
393 $unmerged = $this->openapi->_unmerged;
394 $this->openapi->_unmerged = [];
395 $analysis = new Analysis([$this->openapi], $this->context);
396 $this->openapi->_unmerged = $unmerged;
397
398 return $analysis;
399 }
400
401 /**
402 * Analysis with only the annotations that not merged.
403 */
404 public function unmerged(): Analysis
405 {
406 return $this->split()->unmerged;
407 }
408
409 /**
410 * Split the annotation into two analysis.
411 * One with annotations that are merged and one with annotations that are not merged.
412 *
413 * @return \stdClass {merged: Analysis, unmerged: Analysis}
414 */
415 public function split(): \stdClass
416 {
417 $result = new \stdClass();
418 $result->merged = $this->merged();
419 $result->unmerged = new Analysis([], $this->context);
420 foreach ($this->annotations as $annotation) {
421 if ($result->merged->annotations->offsetExists($annotation) === false) {
422 $result->unmerged->annotations->offsetSet($annotation, $this->annotations[$annotation]);
423 }
424 }
425
426 return $result;
427 }
428
429 public function validate(): bool
430 {
431 if (!$this->openapi instanceof OA\OpenApi) {
432 $this->context->logger->warning('No openapi target set. Run the MergeIntoOpenApi processor before validate()');
433
434 return false;
435 }
436
437 $isValid = true;
438 $version = $this->openapi->openapi;
439 $context = new \stdClass();
440
441 foreach ($this->collectAnnotations($this->openapi) as $annotation) {
442 $isValid = $annotation->validate($this, $version, $context) && $isValid;
443 }
444
445 return $isValid;
446
447 }
448
449 /**
450 * @return array<OA\AbstractAnnotation>
451 */
452 protected function collectAnnotations(OA\AbstractAnnotation $root): array
453 {
454 $annotations = [$root];
455
456 foreach (get_object_vars($root) as $field => $value) {
457 if (null === $value || Generator::isDefault($value) || is_scalar($value) || in_array($field, $root::$_blacklist)) {
458 continue;
459 }
460
461 if ($value instanceof OA\AbstractAnnotation) {
462 $annotations = array_merge($annotations, $this->collectAnnotations($value));
463 } elseif (is_array($value)) {
464 foreach ($value as $item) {
465 if ($item instanceof OA\AbstractAnnotation) {
466 $annotations = array_merge($annotations, $this->collectAnnotations($item));
467 }
468 }
469 }
470 }
471
472 return $annotations;
473 }
474 }