Report what a function assigns that its @var tag does not accept

[ondrejmirtes]

A @var tag above a value that doesn't decide the variable's type — $x = null, $x = [], a scalar, new Foo() of a generic class, or static $x — is effectively the declared type of the variable. Every write to it afterwards must keep it within the tag, and a write that doesn't is reported on its own line:

function doFoo(): void
{
	/** @var array<int> $a */
	$a = [];
	$a[] = 1;
	$a[] = 'foo';   // PHPDoc tag @var with type array<int> does not accept type array<int|string> assigned to $a.
	$a[] = 2;       // fine - judged on its own, not coloured by the previous line
}

function writes(): void
{
	/** @var 'a'|'b' $s */
	$s = 'a';
	$s .= 'x';      // ... does not accept type 'ax'|'bx' assigned to $s.

	/** @var list<int> $l */
	$l = [];
	$l[50] = 1;     // ... does not accept type non-empty-array<int<0, max>, int> assigned to $l.

	/** @var int<0, 5> $n */
	$n = 0;
	$n++;           // ... does not accept type int<1, 6> assigned to $n.
}

function say_HELLO(): void
{
	/** @var string $name */
	static $name = 'world';
	$name = [];     // ... with type string does not accept type array assigned to $name.
}

function doBar(): void
{
	/** @var Collection<int|string> $c */
	$c = new Collection([]);  // ... does not accept type Collection<int> assigned to $c.
	$c->add(1);
}

This is the opposite direction of the existing inline @var check. That check makes the tag a subtype of the assigned expression's native type; here the tag has to be a supertype of what is written later. The declared value itself is still left to the existing check.

Bleeding edge only (featureToggles.varTagsReflectUsages). Like #6604 and #6617, it runs inside the two-pass body walk of unresolvedTemplateArguments.

How it works

Find the writes (first commit, engine + turbo). VarTagUsagesInference finds the top-level declarations in a body and every write to their variables after them:

• assignments;
• compound assignments (.=, +=, …);
• ++/--;
• offset writes ($a[] = …, $a[50] = …, nested dims);
• destructuring;
• all of the above inside a closure that uses the variable by reference.

At the end of the body walk, each write is evaluated once more from the variable holding the tag's type. A write after a wrong one, or inside a loop, is therefore judged on its own. VarTagUsagesNode carries the variable's type after the write.

For a generic new, the driver walks the body once more without the tag, re-walking only the statements that read what changed. The node carries the declared value with the template arguments that walk infers (Collection<int> from $c->add(1)), both generalized like inferred ones and precise.

Check it (second commit, VarTagReflectsUsagesRule, level 2, identifier varTag.usages):

• The type after each write must be a subtype of the tag. The error goes on the write's line, or on the declaration for a generic new.
• Template arguments count as fine when the tag accepts either the generalized or the precise ones, so Transaction<true> over an inferred bool argument isn't reported. A template argument nothing in the body constrains is unknown.
• The check follows the rule level through the new RuleLevelHelper::isSuperTypeOf(), the accepts() counterpart for this direction:
  • a type the tag is only maybe a supertype of is reported from level 7 on (array<int> vs array<int|string>);
  • a type holding mixed or a benevolent union that the level does not check yet is judged like accepts() judges it: mixed fits anywhere, and a benevolent union fits where one of its members does. So $list[] = $key with an (int|string) key is fine, and array<mixed> into array<string, Foo> is reported only from level 9.
• A tag wider than what the function assigns (an interface over its implementation, list<T> over non-empty lists) is not reported.
• Self-analysis found one true positive: the @var list<…> over the two-pass driver's statement entries, which are keyed by the statement list's keys. It is now array<int, …>, matching the functions it's passed to.

Verification

• make tests is green with the extension off and loaded.
• Walk-trace (PHP vs native) is identical on the full corpus and on the rule fixtures.
• Side-by-side, smoke and signature parity pass. make phpstan and cs are clean.
• VarTagReflectsUsagesRuleTest runs one fixture in three configurations: level-7+ behaviour, without union checks, and with mixed checked. The fixture covers:
  • wrong elements, compound assignments, increments and decrements;
  • offset writes on a list, destructuring;
  • writes in loops and after a wrong write;
  • generic new with inferred template arguments;
  • by-ref closures, static caches;
  • literal element types, untyped sources, unconstrained template arguments and benevolent keys.
• bug-14198 covers the issue's snippet verbatim.

Closes phpstan/phpstan#14198

🤖 Generated with Claude Code

https://claude.ai/code/session_01VpbB99tJfUmeArX74xqvHv