| 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 |
} |