|
| 1 | +<?php declare(strict_types = 1); |
| 2 | + |
| 3 | +namespace PHPStan\Analyser\Generics; |
| 4 | + |
| 5 | +use PhpParser\Node; |
| 6 | +use PhpParser\Node\Expr; |
| 7 | +use PHPStan\Analyser\MutatingScope; |
| 8 | +use PHPStan\DependencyInjection\AutowiredParameter; |
| 9 | +use PHPStan\DependencyInjection\AutowiredService; |
| 10 | +use PHPStan\Turbo\ShadowedByTurboExtension; |
| 11 | +use function array_fill_keys; |
| 12 | +use function array_keys; |
| 13 | +use function array_pop; |
| 14 | +use function count; |
| 15 | +use function is_array; |
| 16 | +use function is_string; |
| 17 | +use function preg_match; |
| 18 | +use function spl_object_id; |
| 19 | + |
| 20 | +/** |
| 21 | + * Finds the `@var` declarations of a function-like body whose type the |
| 22 | + * assigned value does not decide - `null`, `[]`, a scalar, a `new` of a |
| 23 | + * generic class, and any `static` variable - and the writes to those |
| 24 | + * variables after them. Such a tag is the declared type of the variable: |
| 25 | + * every value the body writes to it has to fit, and the value of a generic |
| 26 | + * `new` has to fit with the template arguments the body infers when the tag |
| 27 | + * is left out (see StatementsHandler::processBodyStmtNodesTwoPass()). |
| 28 | + * VarTagReflectsUsagesRule checks both. |
| 29 | + */ |
| 30 | +#[AutowiredService] |
| 31 | +#[ShadowedByTurboExtension(implementation: __DIR__ . '/../../../turbo-ext/src/VarTagUsagesInference.cpp')] |
| 32 | +final class VarTagUsagesInference |
| 33 | +{ |
| 34 | + |
| 35 | + private const DECLARATIONS_ATTRIBUTE = 'varTagUsagesDeclarations'; |
| 36 | + |
| 37 | + private const WRITES_ATTRIBUTE = 'varTagUsagesWrites'; |
| 38 | + |
| 39 | + public function __construct( |
| 40 | + #[AutowiredParameter(ref: '%featureToggles.varTagsReflectUsages%')] |
| 41 | + private bool $enabled, |
| 42 | + ) |
| 43 | + { |
| 44 | + } |
| 45 | + |
| 46 | + /** |
| 47 | + * The top-level statements `/** @var T $x *\/ $x = <value>;` of the body |
| 48 | + * whose value does not decide the type and `/** @var T *\/ static $x;`, |
| 49 | + * with their index and the variable's name. |
| 50 | + * |
| 51 | + * @param Node\Stmt[] $stmts |
| 52 | + * @return list<array{Node\Stmt, int, string}> |
| 53 | + */ |
| 54 | + public function getDeclarations(Node $functionLike, array $stmts): array |
| 55 | + { |
| 56 | + if (!$this->enabled) { |
| 57 | + return []; |
| 58 | + } |
| 59 | + |
| 60 | + /** @var list<array{Node\Stmt, int, string}>|null $cached */ |
| 61 | + $cached = $functionLike->getAttribute(self::DECLARATIONS_ATTRIBUTE); |
| 62 | + if ($cached !== null) { |
| 63 | + return $cached; |
| 64 | + } |
| 65 | + |
| 66 | + $declarations = []; |
| 67 | + foreach ($stmts as $index => $stmt) { |
| 68 | + $name = self::getDeclaredVariableName($stmt); |
| 69 | + if ($name === null) { |
| 70 | + continue; |
| 71 | + } |
| 72 | + $docComment = $stmt->getDocComment(); |
| 73 | + if ($docComment === null || preg_match('~@(?:phpstan-|psalm-)?var\s~', $docComment->getText()) !== 1) { |
| 74 | + continue; |
| 75 | + } |
| 76 | + $declarations[] = [$stmt, $index, $name]; |
| 77 | + } |
| 78 | + $functionLike->setAttribute(self::DECLARATIONS_ATTRIBUTE, $declarations); |
| 79 | + |
| 80 | + return $declarations; |
| 81 | + } |
| 82 | + |
| 83 | + /** |
| 84 | + * The writes to the declared variables after their declarations: the |
| 85 | + * assignments, compound assignments, increments and decrements of the |
| 86 | + * variable, of an offset in it, or destructuring into it - also in a |
| 87 | + * closure that uses the variable by reference - with the key of the |
| 88 | + * declaration in getDeclarations() and the variable's name. |
| 89 | + * |
| 90 | + * @param Node\Stmt[] $stmts |
| 91 | + * @return list<array{Expr, int, string}> |
| 92 | + */ |
| 93 | + public function getWrites(Node $functionLike, array $stmts): array |
| 94 | + { |
| 95 | + $declarations = $this->getDeclarations($functionLike, $stmts); |
| 96 | + if ($declarations === []) { |
| 97 | + return []; |
| 98 | + } |
| 99 | + |
| 100 | + /** @var list<array{Expr, int, string}>|null $cached */ |
| 101 | + $cached = $functionLike->getAttribute(self::WRITES_ATTRIBUTE); |
| 102 | + if ($cached !== null) { |
| 103 | + return $cached; |
| 104 | + } |
| 105 | + |
| 106 | + $declarationsByName = []; |
| 107 | + $declaringAssigns = []; |
| 108 | + foreach ($declarations as $key => [$stmt, , $name]) { |
| 109 | + $declarationsByName[$name][] = [$stmt->getEndFilePos(), $key]; |
| 110 | + if (!$stmt instanceof Node\Stmt\Expression) { |
| 111 | + continue; |
| 112 | + } |
| 113 | + $declaringAssigns[spl_object_id($stmt->expr)] = true; |
| 114 | + } |
| 115 | + $writes = []; |
| 116 | + $stack = []; |
| 117 | + $names = array_fill_keys(array_keys($declarationsByName), true); |
| 118 | + foreach ($stmts as $stmt) { |
| 119 | + $stack[] = [$stmt, $names]; |
| 120 | + } |
| 121 | + while (count($stack) > 0) { |
| 122 | + [$node, $visibleNames] = array_pop($stack); |
| 123 | + if ($node instanceof Expr\Closure) { |
| 124 | + // its own variables, except those it uses by reference |
| 125 | + $byRefNames = []; |
| 126 | + foreach ($node->uses as $use) { |
| 127 | + if (!$use->byRef || !is_string($use->var->name) || !isset($visibleNames[$use->var->name])) { |
| 128 | + continue; |
| 129 | + } |
| 130 | + $byRefNames[$use->var->name] = true; |
| 131 | + } |
| 132 | + if ($byRefNames === []) { |
| 133 | + continue; |
| 134 | + } |
| 135 | + foreach ($node->stmts as $closureStmt) { |
| 136 | + $stack[] = [$closureStmt, $byRefNames]; |
| 137 | + } |
| 138 | + continue; |
| 139 | + } |
| 140 | + if ($node instanceof Node\FunctionLike || $node instanceof Node\Stmt\ClassLike) { |
| 141 | + continue; |
| 142 | + } |
| 143 | + $target = null; |
| 144 | + if ( |
| 145 | + $node instanceof Expr\Assign |
| 146 | + || $node instanceof Expr\AssignOp |
| 147 | + || $node instanceof Expr\PreInc |
| 148 | + || $node instanceof Expr\PreDec |
| 149 | + || $node instanceof Expr\PostInc |
| 150 | + || $node instanceof Expr\PostDec |
| 151 | + ) { |
| 152 | + $target = $node->var; |
| 153 | + } |
| 154 | + if ($target !== null && !isset($declaringAssigns[spl_object_id($node)])) { |
| 155 | + foreach (self::getWrittenNames($target) as $name) { |
| 156 | + if (!isset($visibleNames[$name])) { |
| 157 | + continue; |
| 158 | + } |
| 159 | + $declarationKey = null; |
| 160 | + foreach ($declarationsByName[$name] as [$declarationEnd, $key]) { |
| 161 | + if ($declarationEnd >= $node->getStartFilePos()) { |
| 162 | + continue; |
| 163 | + } |
| 164 | + $declarationKey = $key; |
| 165 | + } |
| 166 | + if ($declarationKey === null) { |
| 167 | + continue; |
| 168 | + } |
| 169 | + $writes[] = [$node, $declarationKey, $name]; |
| 170 | + } |
| 171 | + } |
| 172 | + foreach ($node->getSubNodeNames() as $subNodeName) { |
| 173 | + $subNode = $node->$subNodeName; |
| 174 | + if ($subNode instanceof Node) { |
| 175 | + $stack[] = [$subNode, $visibleNames]; |
| 176 | + } elseif (is_array($subNode)) { |
| 177 | + foreach ($subNode as $item) { |
| 178 | + if (!$item instanceof Node) { |
| 179 | + continue; |
| 180 | + } |
| 181 | + $stack[] = [$item, $visibleNames]; |
| 182 | + } |
| 183 | + } |
| 184 | + } |
| 185 | + } |
| 186 | + $functionLike->setAttribute(self::WRITES_ATTRIBUTE, $writes); |
| 187 | + |
| 188 | + return $writes; |
| 189 | + } |
| 190 | + |
| 191 | + /** |
| 192 | + * The variables a write target writes: the variable, an offset in it, or |
| 193 | + * the destructured ones. |
| 194 | + * |
| 195 | + * @return list<string> |
| 196 | + */ |
| 197 | + private static function getWrittenNames(Expr $target): array |
| 198 | + { |
| 199 | + while ($target instanceof Expr\ArrayDimFetch) { |
| 200 | + $target = $target->var; |
| 201 | + } |
| 202 | + if ($target instanceof Expr\Variable) { |
| 203 | + return is_string($target->name) ? [$target->name] : []; |
| 204 | + } |
| 205 | + if (!$target instanceof Expr\List_ && !$target instanceof Expr\Array_) { |
| 206 | + return []; |
| 207 | + } |
| 208 | + |
| 209 | + $names = []; |
| 210 | + foreach ($target->items as $item) { |
| 211 | + if ($item === null) { |
| 212 | + continue; |
| 213 | + } |
| 214 | + foreach (self::getWrittenNames($item->value) as $name) { |
| 215 | + $names[] = $name; |
| 216 | + } |
| 217 | + } |
| 218 | + |
| 219 | + return $names; |
| 220 | + } |
| 221 | + |
| 222 | + /** Whether the walk leaves the @var tags of the statement out. */ |
| 223 | + public function isSuppressed(MutatingScope $scope, Node\Stmt $stmt): bool |
| 224 | + { |
| 225 | + $frame = $scope->getCurrentTemplateArgumentFrame(); |
| 226 | + |
| 227 | + return $frame !== null && $frame->isVarTagSuppressed($stmt); |
| 228 | + } |
| 229 | + |
| 230 | + private static function getDeclaredVariableName(Node\Stmt $stmt): ?string |
| 231 | + { |
| 232 | + if ($stmt instanceof Node\Stmt\Static_) { |
| 233 | + // what the previous calls left decides the type, not the default |
| 234 | + if (count($stmt->vars) !== 1 || !is_string($stmt->vars[0]->var->name)) { |
| 235 | + return null; |
| 236 | + } |
| 237 | + |
| 238 | + return $stmt->vars[0]->var->name; |
| 239 | + } |
| 240 | + |
| 241 | + if ( |
| 242 | + !$stmt instanceof Node\Stmt\Expression |
| 243 | + || !$stmt->expr instanceof Expr\Assign |
| 244 | + || !$stmt->expr->var instanceof Expr\Variable |
| 245 | + || !is_string($stmt->expr->var->name) |
| 246 | + || !self::isUndecidingValue($stmt->expr->expr) |
| 247 | + ) { |
| 248 | + return null; |
| 249 | + } |
| 250 | + |
| 251 | + return $stmt->expr->var->name; |
| 252 | + } |
| 253 | + |
| 254 | + private static function isUndecidingValue(Expr $expr): bool |
| 255 | + { |
| 256 | + return $expr instanceof Expr\ConstFetch |
| 257 | + || $expr instanceof Node\Scalar |
| 258 | + || ($expr instanceof Expr\Array_ && $expr->items === []) |
| 259 | + || $expr instanceof Expr\New_; |
| 260 | + } |
| 261 | + |
| 262 | +} |
0 commit comments