1: <?php declare(strict_types = 1);
2:
3: namespace PHPStan\Reflection;
4:
5: use PHPStan\PhpDoc\ResolvedPhpDocBlock;
6: use PHPStan\PhpDoc\Tag\AssertTag;
7: use PHPStan\Turbo\ShadowedByTurboExtension;
8: use PHPStan\Type\Type;
9: use PHPStan\Type\TypeCombinator;
10: use function array_filter;
11: use function array_map;
12: use function array_merge;
13: use function count;
14: use function sprintf;
15:
16: /**
17: * Collection of @phpstan-assert annotations on a function or method.
18: *
19: * PHPStan supports type assertions via PHPDoc annotations:
20: * - `@phpstan-assert Type $param` — narrows the parameter type unconditionally
21: * - `@phpstan-assert-if-true Type $param` — narrows when the method returns true
22: * - `@phpstan-assert-if-false Type $param` — narrows when the method returns false
23: *
24: * This class collects all such assertions and provides methods to retrieve them
25: * by condition type. It also handles negation: an `@phpstan-assert-if-true` assertion
26: * is automatically negated and included in the `getAssertsIfFalse()` result.
27: *
28: * Returned by ExtendedMethodReflection::getAsserts() and FunctionReflection::getAsserts().
29: *
30: * @api
31: */
32: #[ShadowedByTurboExtension(implementation: __DIR__ . '/../../turbo-ext/src/Assertions.cpp')]
33: final class Assertions
34: {
35:
36: private static ?self $empty = null;
37:
38: /**
39: * @param AssertTag[] $asserts
40: */
41: private function __construct(private array $asserts)
42: {
43: }
44:
45: /** @return AssertTag[] */
46: public function getAll(): array
47: {
48: return $this->asserts;
49: }
50:
51: /**
52: * Unconditional assertions — narrow parameter types regardless of the method's return value.
53: *
54: * @return AssertTag[]
55: */
56: public function getAsserts(): array
57: {
58: return array_filter($this->asserts, static fn (AssertTag $assert) => $assert->getIf() === AssertTag::NULL);
59: }
60:
61: /**
62: * Includes @phpstan-assert-if-true tags and negated @phpstan-assert-if-false tags.
63: *
64: * @return AssertTag[]
65: */
66: public function getAssertsIfTrue(): array
67: {
68: $asserts = [];
69: $negatedAsserts = [];
70: foreach ($this->asserts as $assert) {
71: if ($assert->getIf() === AssertTag::IF_TRUE) {
72: $asserts[] = $assert;
73: } elseif ($assert->getIf() === AssertTag::IF_FALSE && !$assert->isEquality()) {
74: $negatedAsserts[] = $assert->negate();
75: }
76: }
77:
78: return array_merge($asserts, $negatedAsserts);
79: }
80:
81: /**
82: * Includes @phpstan-assert-if-false tags and negated @phpstan-assert-if-true tags.
83: *
84: * @return AssertTag[]
85: */
86: public function getAssertsIfFalse(): array
87: {
88: $asserts = [];
89: $negatedAsserts = [];
90: foreach ($this->asserts as $assert) {
91: if ($assert->getIf() === AssertTag::IF_FALSE) {
92: $asserts[] = $assert;
93: } elseif ($assert->getIf() === AssertTag::IF_TRUE && !$assert->isEquality()) {
94: $negatedAsserts[] = $assert->negate();
95: }
96: }
97:
98: return array_merge($asserts, $negatedAsserts);
99: }
100:
101: /** @param callable(Type): Type $callable */
102: public function mapTypes(callable $callable): self
103: {
104: $assertTagsCallback = static fn (AssertTag $tag): AssertTag => $tag->withType($callable($tag->getType()));
105:
106: return self::create(array_map($assertTagsCallback, $this->asserts));
107: }
108:
109: /**
110: * @deprecated use union() or intersect() instead
111: */
112: public function intersectWith(Assertions $other): self
113: {
114: return $this->union($other);
115: }
116:
117: public function union(Assertions $other): self
118: {
119: if ($this === self::$empty) {
120: return $other;
121: }
122: if ($other === self::$empty) {
123: return $this;
124: }
125:
126: return self::create(array_merge($this->getAll(), $other->getAll()));
127: }
128:
129: public function intersect(Assertions $other): self
130: {
131: if ($this === self::$empty) {
132: return $other;
133: }
134: if ($other === self::$empty) {
135: return $this;
136: }
137:
138: $otherAsserts = $other->getAll();
139: $thisAsserts = $this->getAll();
140:
141: $merged = [];
142: foreach ($thisAsserts as $thisAssert) {
143: $key = self::getAssertKey($thisAssert);
144:
145: foreach ($otherAsserts as $otherAssert) {
146: if (self::getAssertKey($otherAssert) !== $key) {
147: continue;
148: }
149:
150: $merged[] = $thisAssert->withType(TypeCombinator::union($thisAssert->getType(), $otherAssert->getType()));
151: }
152: }
153:
154: return self::create($merged);
155: }
156:
157: private static function getAssertKey(AssertTag $assert): string
158: {
159: return sprintf(
160: '%s-%s-%s',
161: $assert->getParameter()->describe(),
162: $assert->getIf(),
163: $assert->isNegated() ? '1' : '0',
164: );
165: }
166:
167: /**
168: * @param AssertTag[] $asserts
169: */
170: private static function create(array $asserts): self
171: {
172: if (count($asserts) === 0) {
173: return self::createEmpty();
174: }
175: return new self($asserts);
176: }
177:
178: public static function createEmpty(): self
179: {
180: $empty = self::$empty;
181:
182: if ($empty !== null) {
183: return $empty;
184: }
185:
186: $empty = new self([]);
187: self::$empty = $empty;
188:
189: return $empty;
190: }
191:
192: public static function createFromResolvedPhpDocBlock(ResolvedPhpDocBlock $phpDocBlock): self
193: {
194: $tags = $phpDocBlock->getAssertTags();
195:
196: return self::create($tags);
197: }
198:
199: /**
200: * @param AssertTag[] $assertTags
201: */
202: public static function createFromAssertTags(array $assertTags): self
203: {
204: return self::create($assertTags);
205: }
206:
207: }
208: