Do not narrow the left side of ?? to non-null when the coalesce context still permits a falsey value

[phpstan-bot]

Summary

After a check like if (($arr[$key] ?? null) === false) { return; }, PHPStan wrongly memorized $arr[$key] as always existing. This produced false-positive isset.offset and nullCoalesce.offset errors ("Offset … always exists and is not nullable") on subsequent isset($arr[$key]) / $arr[$key] ?? … uses, even though $key may not be present in the array. This is a follow-up to #11708, which only fixed the preg_match variant.

The fix teaches CoalesceHandler not to narrow the left side of ?? to non-null when the surrounding condition only proves the coalesce is not exactly false — because a missing offset produces null, and null !== false.

Changes

• src/Analyser/ExprHandler/CoalesceHandler.php: guarded the branch that narrows $expr->left to non-null with !$context->falsey(). That branch previously fired for any context carrying the TRUE bit, including the createFalse()->negate() ("anything but false") context, which still permits a null result.
• tests/PHPStan/Rules/Variables/data/bug-13488.php: regression fixture based on the issue's playground sample, extended with the analogous !== false and falsey-right-operand (?? 0) cases.
• tests/PHPStan/Rules/Variables/IssetRuleTest.php and NullCoalesceRuleTest.php: added testBug13488() expecting no errors (both rules were affected by the same wrong narrowing).

Root cause

EqualityTypeSpecifyingHelper::specifyTypesForConstantBinaryExpression() translates $x === false being false into a truthy-style narrowing by calling specifyTypesInCondition($x, createFalse()->negate()). That context (0b1011) means "anything but false" and correctly yields no narrowing for ordinary expressions via the default handler. However, CoalesceHandler::specifyTypes() treated any context with the TRUE bit as permission to strip null from the ?? left operand (and thus mark the offset/variable as set). For $arr[$key] ?? null, a missing offset makes the whole expression null, which satisfies !== false, so the offset cannot be assumed to exist.

The pattern — "not-false does not imply not-null/truthy" — affects every strict comparison that produces the not-false context:

• ($arr[$key] ?? null) === false (reported case, false branch)
• ($arr[$key] ?? null) !== false (true branch)
• ($arr[$key] ?? 0) === false and any other falsey right operand of ??

All three are fixed by the single guard. The loose ==/!= variants were probed and are intentionally left untouched: null == false is true, so ($arr[$key] ?? null) != false genuinely does imply the offset exists.

Test

• IssetRuleTest::testBug13488 and NullCoalesceRuleTest::testBug13488 run the reproducer at level with treatPhpDocTypesAsCertain and assert no errors. Both fail on the unfixed tree (they report the isset.offset / nullCoalesce.offset false positives) and pass with the fix.
• The fixture also covers the analogous !== false and ?? 0 cases, which are false positives before the fix and clean afterwards.

Fixes phpstan/phpstan#13488

[staabm]

I always mix up ->false and ->falsey.

would be great to also have tests for ==false, ==true

[phpstan-bot]

Done. Here's what I did to address staabm's review:

Review point 1: "I always mix up ->false and ->falsey"

No code change needed — the guard correctly uses ->falsey(). I verified this empirically: reverting the guard makes the strict testBug13488 fail (it reports the false-positive isset.offset errors), and restoring it passes. The !$context->falsey() check is what blocks the createFalse()->negate() ("anything but false") context, which is exactly the buggy narrowing path. ->false() would be the wrong method here.

Review point 2: "would be great to also have tests for ==false, ==true"

Added a new fixture tests/PHPStan/Rules/Variables/data/bug-13488-loose.php covering all four loose variants, plus testBug13488Loose() in both IssetRuleTest and NullCoalesceRuleTest. I determined the correct expectations empirically rather than guessing:

Condition (true branch)	Matches	Offset must exist?	Errors expected
($foo[$k] ?? null) == false	false or null (missing)	no	none
($foo[$k] ?? null) == true	true only	yes	isset.offset + nullCoalesce.offset
($foo[$k] ?? null) != false	true only	yes	isset.offset + nullCoalesce.offset
($foo[$k] ?? null) != true	false or null (missing)	no	none

This documents that loose comparison narrowing is correct (because null == false), which is why the fix intentionally left the ==/!= path untouched — the contrast the reviewer wanted to see spelled out.

Verification

• testBug13488 (strict) and testBug13488Loose (loose) — 4/4 pass.
• Full IssetRuleTest + NullCoalesceRuleTest — 66/66 pass.
• make phpstan — no errors.

Committed as a separate logical change and pushed to the PR branch.