The complexity is there precisely because I want to allow:

/** @var int[] $foo */
$foo = returnListOfIntegers();

Because it's harmless and PHPStan cannot be too annoying.

After one of your changes (#2738) I had to spend some time iterating so that the rule isn't too annoying:

• 42f6c2e
• 67893d4
• 256e8dc

As it stands right now when someone comes to me with a question regarding "PHPStan complains about my @var, what I should do?" I know how to help them and how they should improve their code.

After #2738 I found situations in real-world code that I myself didn't know how to solve (aside from deleting @var which led to other issues), that's why I needed to adjust it.

Inline @var PHPDoc is a horrible multi-faceted beast and we need to have the current heuristics so that PHPStan strikes the right balance between being useful and too pedantic.

I believe there should be some option to have it strictly based on type system, not based on your taste. This way (with all this complexity), there will be many more holes - just found another issue (array{id: int}|null can be widened to mixed[]|null)

Also, allowing list to array widening may seem ok-ish for one, but we utilize lists a lot and this is degrading our efforts.

All those holes are hard to spot, I invested quite some time to find all those I reported (1, 2, 3, 4). But if you insist keeping this as-is, I can always add the strict & proper behaviour to https://github.com/shipmonk-rnd/phpstan-rules

Last thing to consider: maybe if there was some way to do "declare variable type" in PHPStan (like some @type), people would stop abusing vardoc for that and many of those edgecases you want to adjust may disappear.

An idea: @phpstan-var where we can afford to be a bit stricter.

Not really a fan of that idea. I think people are used to that

• @phpstan-param and @psalm-param and @param
• @phpstan-return and @psalm-return and @return

are almost synonyms. With some exceptions in IDEs.

@ondrejmirtes What about feature flag strictVarDocChecks ?

@janedbal Feature flags are for things we eventually want to enable for everybody (in the next major version). Which already applies to this rule (it's only in bleeding edge).

But I don't want this proposed behaviour in the next major version.

If you mean a new permanent option like listed here https://phpstan.org/config-reference#stricter-analysis, then sure, I'd merge that, there's already reportWrongPhpDocTypeInVarTag that makes it a bit more strict (and is enabled in phpstan-strict-rules).

Yeah, I mean regular option. Thx, I'll prepare that.

I suggest to name it stricterPhpDocTypeCheckInVarTag to correlate with existing one:

- reportWrongPhpDocTypeInVarTag: true
- stricterPhpDocTypeCheckInVarTag: true