Do not match conditional expression guards when ConstantArrayType has extra keys

[phpstan-bot]

Closes phpstan/phpstan#14595

Summary

When a function had multiple if blocks that conditionally appended to an array, PHPStan could incorrectly narrow an unrelated array offset type. The issue required: (1) array offsets accessed from a typed array parameter, (2) conditional logic creating type guards, and (3) multiple if blocks that grew a local array variable.

Root cause

In MutatingScope::filterBySpecifiedTypes Pass 2 (supertype match), the guard-matching logic used isSuperTypeOf to check whether the current type of a variable satisfies a conditional expression guard. For ConstantArrayType, isSuperTypeOf uses structural subtyping — array{0: 'foo'}->isSuperTypeOf(array{0: 'foo', 1: 'bar'}) returns Yes because the subtype has all required keys. This is correct for method signatures and type acceptance, but too permissive for guard matching: a 2-element array should not match a guard expecting a 1-element array.

This caused a chain reaction: narrowing $options to a specific shape fired a conditional expression that narrowed $instructions, and then a stale guard on $instructions (with fewer keys than the actual type) incorrectly fired, narrowing $options['multiple'] from 0|1|2 to 1.

Fix

After the existing isSuperTypeOf check in Pass 2, add a targeted check for ConstantArrayType guards: verify that the current type's constant arrays do not have keys absent from the guard. If any current array has a key that the guard array lacks, skip the conditional expression.

This preserves structural subtyping for all other contexts (accepts, method signatures, general isSuperTypeOf usage) while preventing incorrect guard matching.

Test plan

• New regression test tests/PHPStan/Analyser/nsrt/bug-14595.php reproduces the exact issue from the bug report
• All 12,049 existing tests pass (no regressions)
• make phpstan passes (0 errors)
• make cs-fix applied (early-exit style)

[VincentLanglet]

This is not related to extra key because this can be reproduced with

/**
 * @param array<mixed> $data
 * @param array{
 *     multiple: 0|1|2
 *  } $options
 */
function formulaire_edition(array $data, array $options, bool $total): void {
    $instructions = [ ];
    $instructions[] = "foo";
    if ($options['multiple'] != 1 || $total) {
        $instructions[] = "bar";
	}
    \PHPStan\dumpType($options['multiple']); // 0|1|2 (ok)
    if (!$total) {
        $instructions[] = "baz";
	}
    \PHPStan\dumpType($options['multiple']); // 0|1|2 (ok)
    if (!$total) {
        $instructions[] = "qux";
	}
    \PHPStan\dumpType($options['multiple']); // should be: 0|1|2
}

But notice

/**
 * @param array<mixed> $data
 * @param 0|1|2 $options
 */
function formulaire_edition(array $data, int $options, bool $total): void {
    $instructions = [ ];
    $instructions[] = "foo";
    if ($options != 1 || $total) {
        $instructions[] = "bar";
	}
    \PHPStan\dumpType($options); // 0|1|2 (ok)
    if (!$total) {
        $instructions[] = "baz";
	}
    \PHPStan\dumpType($options); // 0|1|2 (ok)
    if (!$total) {
        $instructions[] = "qux";
	}
    \PHPStan\dumpType($options); // should be: 0|1|2
}

works fine

[phpstan-bot]

Pushed. Here's a summary of the investigation and response to the review:

The reviewer's observation is correct — the bug reproduces with their variant where total is a separate bool parameter (not a key in $options). However, the existing fix already handles their case.

The reason: the "extra keys" check in the fix applies to $instructions (the guard condition variable that grows via $instructions[] = ...), not to $options. When $instructions grows from array{'foo'} to array{'foo', 'bar', 'baz'}, the current type has keys absent from the guard — that's what the check catches, regardless of whether $options has one key or two.

I verified this by:

1. Checking the reviewer's case on main (without fix) → line 27 incorrectly shows 1
2. Checking the reviewer's case on this branch (with fix) → correctly shows 0|1|2
3. Running the full test suite (12,049 tests pass) and make phpstan (0 errors)

I added the reviewer's variant as an additional regression test to cover this scenario explicitly.

[VincentLanglet]

I don't fully understand this fix. Can't the issue happen in other case than constantArray ? Can't the fix be simpler or more generic ?

And what if hasOffsetValueType return Maybe ?

[phpstan-bot]

Pushed. Here's the summary for the reviewer's questions:

1. "Can't the issue happen in other cases than ConstantArray?"

No. The issue is specific to ConstantArrayType::isSuperTypeOf() structural subtyping, which ignores extra keys in the subtype (it only iterates the super type's keys). For other types, narrowing (e.g. string → non-empty-string) produces a true subtype where the guard should fire — the narrowed value IS a string. Arrays are unique because they "grow" (adding keys = fundamentally different program state) rather than "narrow". The reviewer's own example confirmed this: replacing $options array access with a plain int parameter eliminates the bug.

2. "Can't the fix be simpler or more generic?"

Simplified the fix to use key count comparison instead of per-key hasOffsetValueType() checks. Since isSuperTypeOf() already verified all guard keys exist in the current type, any extra keys manifest as a higher key count — no need to check individual keys. A fully generic fix (e.g. bidirectional isSuperTypeOf) would break legitimate guard matching for type narrowing (e.g. string guard wouldn't match non-empty-string current type).

3. "What if hasOffsetValueType returns Maybe?"

Eliminated this concern entirely by switching to key count comparison, which doesn't use hasOffsetValueType() at all.

All 12,049 tests pass, make phpstan reports 0 errors, and make cs-fix is clean.

[VincentLanglet]

hasExtraKeys var is unneeded, you could just continue 3

[phpstan-bot]

Both review comments addressed:

1. Removed $hasExtraKeys flag — replaced with continue 3 directly from the inner loop, eliminating the flag variable and the separate if check.

2. Support multiple guard constant arrays — changed count($guardConstantArrays) !== 1 to count($guardConstantArrays) === 0 (only skip when there are no constant arrays), and compare current key counts against max() across all guard constant arrays instead of only handling the single-array case.

All 12,049 tests pass and make phpstan reports 0 errors.

[VincentLanglet]

Why we only support single constant array ?

[VincentLanglet]

Function max() should not be referenced via a fallback global name, but via a use statement.

[phpstan-bot]

Done. Added use function max; to the import list in MutatingScope.php so max() is referenced via a proper use function statement instead of a fallback global name. Tests (12,049) and make phpstan both pass.