Report ?? null / ??= null on an always-set left side as an unnecessary null coalesce

[phpstan-bot]

Summary

hello1($name) ?? null is equivalent to hello1($name): a ?? (or ??=) with a null fallback only does something when the left side can be undefined. When the left side is always set, the coalesce never changes the result and is redundant. PHPStan did not report this. This change adds detection for it.

Changes

• conf/config.neon, conf/bleedingEdge.neon, conf/parametersSchema.neon: new featureToggles.unnecessaryNullCoalesce (false by default, true under bleeding edge).
• src/Rules/Variables/NullCoalesceRule.php: after the existing IssetCheck pass, run checkUnnecessaryNullCoalesce(). It reports nullCoalesce.unnecessary when:
  1. the right-hand operand's type is always null (isNull()->yes()), and
  2. the left-hand operand is always set, determined by MutatingScope::issetCheck($left, static fn (): bool => true) === true.
• Removed redundant ?? null instances surfaced by the new rule in PHPStan's own code:
  • src/Analyser/NodeScopeResolver.php (array_last($stmt->cond) ?? null, $parameterType ?? null ×2)
  • src/Type/FileTypeMapper.php (several array_last(...) ?? null)
  • src/Reflection/SignatureMap/Php8SignatureMapProvider.php ($phpDocReturnType ?? null)
• tests/PHPStan/Rules/Variables/NullCoalesceRuleTest.php: pass the toggle, add testBug4337, and account for the extra (correct) report in testBug14213.

Root cause

This is not a regression but a missing check. The existing NullCoalesceRule/IssetCheck only reported the left side being "not nullable" or "always null". The third redundant shape — left always set but nullable, right null — produced no diagnostic because IssetCheck::check() returns null for that case. The fix reuses the already-existing "always set" traversal (MutatingScope::issetCheck) and only adds the new diagnostic when the right side is itself always null.

Analogous cases

All of the following go through the single issetCheck(..., fn () => true) "always set" probe and are covered by one code path; each is exercised in tests/.../data/bug-4337.php:

• function call hello1($name) ?? null (the reported case)
• instance method call $foo->method() ?? null
• static method call Foo::staticMethod() ?? null
• always-defined nullable variable $x ?? null
• always-set nullable property $foo->stringOrNull ?? null
• always-set nullable static property Foo::$staticStringOrNull ?? null
• always-set nullable array offset $arr['a'] ?? null
• assignment form $x ??= null

Negative cases verified to not report: maybe-undefined variable, maybe-undefined array offset, and any ??/??= whose right side is not null. Nullsafe access ($obj?->prop ?? null) is already handled by the existing IssetCheck nullsafe branch, so it short-circuits before the new check and does not double-report.

Test

NullCoalesceRuleTest::testBug4337 analyses data/bug-4337.php (copied from the issue's example plus the analogous constructs) and asserts the eight expected nullCoalesce.unnecessary reports plus the three negative cases. Verified failing before the fix (no errors) and passing after. The full suite, make phpstan, make cs-fix all pass.

Fixes phpstan/phpstan#4337