Debian Codegraph @

vendor/zircote/swagger-php/src/Context.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 use OpenApi\Loggers\DefaultLogger;
11 use Psr\Log\LoggerInterface;
12
13 /**
14 * The context in which the annotation is parsed.
15 *
16 * Contexts are nested to reflect the code/parsing hierarchy. They include useful metadata
17 * which the processors can use to augment the annotations.
18 *
19 * @property string|null $comment The PHP DocComment
20 * @property string|null $filename
21 * @property int|null $line
22 * @property int|null $character
23 * @property string|null $namespace
24 * @property array|null $uses
25 * @property string|null $class
26 * @property string|null $interface
27 * @property string|null $trait
28 * @property string|null $enum
29 * @property array|string|null $extends Interfaces may extend a list of interfaces
30 * @property array|null $implements
31 * @property string|null $method
32 * @property string|null $property
33 * @property \Reflector|null $reflector Optional reflection details
34 * @property bool|null $static Indicate a static method
35 * @property bool|null $generated Indicate the context was generated by a processor,
36 * type resolver or serializer
37 * @property OA\AbstractAnnotation|null $nested
38 * @property list<OA\AbstractAnnotation>|null $annotations
39 * @property list<OA\AbstractAnnotation>|null $other Annotations not related to OpenApi
40 * @property LoggerInterface|null $logger Guaranteed to be set when using the <code>Generator</code>
41 * @property array|null $scanned Details of file scanner when using ReflectionAnalyser
42 * @property string|null $version The OpenAPI version in use
43 */
44 #[\AllowDynamicProperties]
45 class Context implements \Stringable
46 {
47 /**
48 * Prototypical inheritance for properties.
49 */
50 protected ?Context $parent;
51
52 public function __construct(array $properties = [], ?Context $parent = null)
53 {
54 foreach ($properties as $property => $value) {
55 $this->{$property} = $value;
56 }
57 $this->parent = $parent;
58
59 $this->logger = $this->logger ?: new DefaultLogger();
60 }
61
62 /**
63 * Ensure this context is part of the context tree.
64 */
65 public function ensureRoot(?Context $rootContext): void
66 {
67 if ($rootContext === $this) {
68 return;
69 }
70
71 if (!$this->parent) {
72 // use root fallback for these...
73 foreach (['logger', 'version'] as $property) {
74 unset($this->{$property});
75 }
76
77 $this->parent = $rootContext;
78 }
79 }
80
81 /**
82 * Check if a property is set directly on this context and not its parent context.
83 *
84 * Example: $c->is('method') or $c->is('class')
85 */
86 public function is(string $property): bool
87 {
88 return property_exists($this, $property);
89 }
90
91 /**
92 * Check if a property is NOT set directly on this context and its parent context.
93 *
94 * Example: $c->not('method') or $c->not('class')
95 */
96 public function not(string $property): bool
97 {
98 return $this->is($property) === false;
99 }
100
101 /**
102 * Return the context containing the specified property.
103 */
104 public function with(string $property): ?Context
105 {
106 if ($this->is($property)) {
107 return $this;
108 }
109 if ($this->parent instanceof Context) {
110 return $this->parent->with($property);
111 }
112
113 return null;
114 }
115
116 /**
117 * Get the root context.
118 */
119 public function root(): Context
120 {
121 if ($this->parent instanceof Context) {
122 return $this->parent->root();
123 }
124
125 return $this;
126 }
127
128 /**
129 * Get the OpenApi version.
130 *
131 * This is a best guess and only final once parsing is complete.
132 */
133 public function getVersion(): string
134 {
135 return $this->root()->version ?: OA\OpenApi::DEFAULT_VERSION;
136 }
137
138 /**
139 * Check if one of the given version numbers matches the current OpenAPI version.
140 *
141 * @param string|array $version The version to compare. Allows patch version placeholder `x`; e.g. `3.1.x`.
142 */
143 public function isVersion(string|array $version): bool
144 {
145 foreach ((array) $version as $v) {
146 if (OA\OpenApi::versionMatch($this->getVersion(), $v)) {
147 return true;
148 }
149 }
150
151 return false;
152 }
153
154 /**
155 * Export location for debugging.
156 *
157 * @return string Example: "file1.php on line 12"
158 */
159 public function getDebugLocation(): string
160 {
161 $location = '';
162 $fqn = $this->fullyQualifiedName($this->class ?? $this->interface ?? $this->trait ?? $this->enum);
163 if ($fqn && ($this->method || $this->property)) {
164 $location .= $fqn;
165 if ($this->method) {
166 $location .= ($this->static ? '::' : '->') . $this->method . '()';
167 } elseif ($this->property) {
168 $location .= ($this->static ? '::$' : '->') . $this->property;
169 }
170 }
171 if ($this->filename) {
172 if ($location !== '') {
173 $location .= ' in ';
174 }
175 $location .= $this->filename;
176 }
177 if ($this->line) {
178 if ($location !== '') {
179 $location .= ' on';
180 }
181 $location .= ' line ' . $this->line;
182 if ($this->character) {
183 $location .= ':' . $this->character;
184 }
185 }
186
187 return $location;
188 }
189
190 public function __serialize(): array
191 {
192 return array_filter(get_object_vars($this), static function ($value): bool {
193 $rc = is_object($value) ? new \ReflectionClass($value) : null;
194
195 return (!$rc || !$rc->isAnonymous())
196 && !$value instanceof \Reflector
197 && !$value instanceof \Closure;
198 });
199 }
200
201 public function __unserialize(array $data): void
202 {
203 foreach ($data as $name => $value) {
204 $this->{$name} = $value;
205 }
206 }
207
208 /**
209 * Traverse the context tree to get the property value.
210 */
211 public function __get(string $property): mixed
212 {
213 if ($this->parent instanceof Context) {
214 return $this->parent->{$property};
215 }
216
217 return null;
218 }
219
220 public function __toString(): string
221 {
222 return $this->getDebugLocation();
223 }
224
225 public function __debugInfo()
226 {
227 return ['-' => $this->getDebugLocation()];
228 }
229
230 /**
231 * Resolve the given `source` to a fully qualified name.
232 *
233 * @return class-string|null
234 */
235 public function fullyQualifiedName(?string $source): ?string
236 {
237 if ($source === null) {
238 return null;
239 }
240
241 $namespace = $this->namespace ? str_replace('\\\\', '\\', '\\' . $this->namespace . '\\') : '\\';
242
243 $thisSource = $this->class ?? $this->interface ?? $this->trait;
244 if ($thisSource && strcasecmp($source, $thisSource) === 0) {
245 return $namespace . $thisSource;
246 }
247 $pos = strpos($source, '\\');
248 if ($pos !== false) {
249 if ($pos === 0) {
250 // Fully qualified name (\Foo\Bar)
251 return $source;
252 }
253 // Qualified name (Foo\Bar)
254 if ($this->uses) {
255 foreach ($this->uses as $alias => $aliasedNamespace) {
256 $alias .= '\\';
257 if (strcasecmp(substr($source, 0, strlen($alias)), $alias) === 0) {
258 // Aliased namespace (use \Long\Namespace as Foo)
259 return '\\' . $aliasedNamespace . substr($source, strlen($alias) - 1);
260 }
261 }
262 }
263 } elseif ($this->uses) {
264 // Unqualified name (Foo)
265 foreach ($this->uses as $alias => $aliasedNamespace) {
266 if (strcasecmp((string) $alias, $source) === 0) {
267 return '\\' . $aliasedNamespace;
268 }
269 }
270 }
271
272 return $namespace . $source;
273 }
274 }