Fix phpstan/phpstan#14308: Offset 0 should not be optional on non empty list

[phpstan-bot]

Summary

False positive "Offset 0 might not exist on non-empty-list{0?: ...}" was reported when accessing offset 0 on a non-empty list with all optional keys in a constant array shape. The type system correctly knew offset 0 must exist (via IntersectionType::hasOffsetValueType()), but the rule's "report maybes" logic bypassed this by flattening the type into individual array shapes, losing the non-empty constraint.

Changes

• Added early return in src/Rules/Arrays/NonexistentOffsetInArrayDimFetchCheck.php when $type->hasOffsetValueType($dimType)->yes() — if the full type confirms the offset exists, skip the "maybe" reporting entirely
• Added rule regression test in tests/PHPStan/Rules/Arrays/NonexistentOffsetInArrayDimFetchRuleTest.php (testBug14308)
• Added test data in tests/PHPStan/Rules/Arrays/data/bug-14308.php
• Added NSRT test in tests/PHPStan/Analyser/nsrt/bug-14308.php

Root cause

NonexistentOffsetInArrayDimFetchCheck::check() calls TypeUtils::flattenTypes() to decompose types into individual constant array shapes for the "report maybes" logic. For an IntersectionType containing ConstantArrayType (with all optional keys) and NonEmptyArrayType, flattenTypes() extracts the constant arrays via getConstantArrays() and getAllArrays(), but the resulting shapes lose the NonEmptyArrayType constraint. This means the empty array shape is included, which doesn't have offset 0, triggering a false "might not exist" report.

The IntersectionType::hasOffsetValueType() method already correctly handles this case — it checks if the type is a non-empty list and returns yes for offset 0. The fix adds an early return to check the full type before entering the flattening logic.

Test

The regression test reproduces the exact scenario from the issue: array_keys(array_filter([...])) followed by an empty-array check, then accessing offset 0. The rule test expects no errors (false positive eliminated).

Fixes phpstan/phpstan#14308

[phpstan-bot]

Both tests and static analysis passed. The PR is already in good shape — the reviewer's earlier suggestion to extract the hasOffsetValueType result into a variable was already applied in the current code. The review is APPROVED with no outstanding changes needed.

Since there are no code changes to make and the working tree is clean, there's nothing to commit or push.

[staabm]

why the need to drop a test?

[VincentLanglet]

This test was testing that the type is transformed into the description and the description is transformed into the type.

But it's not true anymore.

While

new IntersectionType([
				$listArrayWithAllOptionalKeys,
				new NonEmptyArrayType(),
			])

is transformed into 'list{0: string, 1?: string, 2?: string, 3?: string}', the opposite is not true.

This has to be a TypeCombinator test instead.

[phpstan-bot]

All review comments addressed and pushed. Here's a summary of the changes:

1. TypeCombinator.php - Moved instanceof checks before method calls (isList(), isOptionalKey()) in both condition blocks for short-circuit performance. Also fixed a bug in the second block where $types[$i]->isList() should have been $types[$j]->isList() (since $types[$j] is the ConstantArrayType in that branch, not $types[$i]).

2. TypeToPhpDocNodeTest.php - Moved the test to dataToPhpDocNodeWithoutCheckingEquals instead of deleting it. The test was removed because TypeCombinator::intersect() now simplifies the intersection into a plain ConstantArrayType, so the round-trip assertion ($type->equals($parsedType)) fails — parsing 'non-empty-list{0?: string, ...}' back produces list{0: string, ...}. The toPhpDocNode() output itself is still correct, so the test belongs in the "without checking equals" provider.

[phpstan-bot]

Already handled — all 11588 tests passed and the commit has been pushed.

[phpstan-bot]

The working tree is clean and all previous review comments have been addressed. The review from staabm is an approval with no new code changes requested. There's nothing to do here — the PR is approved and ready to merge.