list is wrongly lost or wrongly kept after a two-dimensional offset assignment like $list[array_key_last($list)][] = … or $matrix[$row][$column] = … #15245

Bug report

When PHPStan infers the type of an array after a nested offset write ($a[X][Y] = $v), it checks the wrong chain link at each dimension. It asks whether an offset expression type is tracked, and whether the list type should be kept, about $a[X] while it writes Y into $a[X], and about $a[X][Y] while it writes X into $a. Depending on the code, this gives a false positive or an unsound list<…> type.

/**
 * @param non-empty-list<list<int>|null> $groups
 * @return non-empty-list<list<int>|null>
 */
function appendToLastGroup(array $groups, int $value): array
{
	$groups[array_key_last($groups)][] = $value;
	\PHPStan\dumpType($groups);
	// expected: non-empty-list<non-empty-list<int>>

	return $groups;
}

/**
 * @param non-empty-list<list<int>> $matrix
 * @return non-empty-list<list<int>>
 */
function setInLastRow(array $matrix, int $column, int $value): array
{
	$matrix[array_key_last($matrix)][$column] = $value;
	\PHPStan\dumpType($matrix);
	// expected: the row is no longer a list ([[]] becomes [[5 => 1]])

	return $matrix;
}

/**
 * @param list<list<int>> $matrix
 * @return list<list<int>>
 */
function setInExistingRow(array $matrix, int $row, int $column, int $value): array
{
	if (isset($matrix[$row])) {
		$matrix[$row][$column] = $value;
		\PHPStan\dumpType($matrix);
		// expected: the row is no longer a list
	}

	return $matrix;
}

Actual output (level 8):

10  Dumped type: non-empty-array<int<0, max>, non-empty-list<int>>
14  Function appendToLastGroup() should return non-empty-list<list<int>|null> but returns non-empty-array<int<0, max>, non-empty-list<int>>.
24  Dumped type: non-empty-list<non-empty-list<int>>
39  Dumped type: non-empty-list<non-empty-list<int>>

• appendToLastGroup() gets a false positive. Writing to $groups[array_key_last($groups)] does not add a key, and the one-dimensional $groups[array_key_last($groups)] = [$value]; keeps the list.
• setInLastRow() and setInExistingRow() get no error. The rows are still typed as lists even though $column can be any integer, so the missing return.type error is a false negative.

Mechanism (line numbers from 2.3.x):

• prepareTarget() reverses the dim-fetch stack so it goes from the innermost link to the outermost one (AssignHandler.php:771). For $a[X][Y] the stack is [$a[X], $a[X][Y]]. $offsetTypes uses the same order, and each entry already carries its own ArrayDimFetch (L779, L804).
• produceArrayDimFetchAssignValueToWrite() walks the chain with foreach (array_reverse($offsetTypes) as $i => [$offsetType]) (L2632), so $i === 0 is the outermost dimension. The other uses of $i agree with this: $unionValues for $i === 0, and $containerKey = $lastDimKey - $i - 1 (L2698).
• However, $arrayDimFetch = $dimFetchStack[$i] ?? null; (L2646) indexes the stack from the innermost end. With two or more dimensions, the outermost offset is paired with the innermost link and vice versa. Only the middle link of an odd-length chain happens to match.
• The mismatched $arrayDimFetch feeds two decisions:
  • $scope->hasExpressionType($arrayDimFetch) (L2650) picks setExistingOffsetValueType(), which keeps list and adds non-empty, over setOffsetValueType(). In setInExistingRow(), isset($matrix[$row]) tracks $matrix[$row], so the write of $column into the row wrongly uses setExistingOffsetValueType().
  • shouldKeepList($arrayDimFetch, …) (L2694, L2731) recognises $list[array_key_last($list)], $list[count($list) - 1] and similar forms. In setInLastRow() that pattern is matched while writing $column into the row, so the row keeps list. In appendToLastGroup() it is checked against $groups[…][] while writing into $groups, so the outer list is dropped.

The false-positive direction only shows up when the element type is not always an array. For list<array> values, IntersectionType::setOffsetValueType() adds list back for any integer offset (src/Type/IntersectionType.php:1154).

The same code is in 2.2.x (AssignHandler.php:2056), so it also reproduces on the playground.

Code snippet that reproduces the problem

https://phpstan.org/r/19c7bbb6-f3fe-4b8c-8a80-672f287f4a97

Expected output

• appendToLastGroup(): non-empty-list<non-empty-list<int>> and no return.type error.
• setInLastRow() and setInExistingRow(): the rows are not typed as list<int>, and the return.type errors are reported.

Suggested fix: use the dim fetch that is paired with the offset in $offsetTypes instead of indexing $dimFetchStack with the reversed loop index:

foreach (array_reverse($offsetTypes) as $i => [$offsetType, $arrayDimFetch]) {

(or $dimFetchStack[$lastDimKey - $i]). With this change, the three dumps become non-empty-list<non-empty-list<int>>, non-empty-list<array<int, int>> and non-empty-list<array<int, int>>. The return.type error moves from appendToLastGroup() to setInLastRow() and setInExistingRow().

Did PHPStan help you today? Did it make you happy in any way?

No response