Track $arr[$key] existence across array_key_first/last + !== null

When `$key = array_key_first/last($arr)` runs against an array that
might be empty, `$arr[$key]` was only registered in scope if the array
was already known non-empty at assignment time. Once the user narrowed
`$key` separately with `if ($key !== null)`, AssignHandler's deep-write
path couldn't see the dim-fetch and fell back to a lossy
`setOffsetValueType`, generalising untouched keys to optional. Attach a
conditional holder at assignment time so the dim-fetch lands in scope
once `$key` is narrowed, matching what `isset($arr[$key])` already does.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: ondrejmirtes

src/Analyser/TypeSpecifier.php

@@ -847,6 +847,31 @@ public function specifyTypesInCondition(
 						$specifiedTypes = $specifiedTypes->unionWith(
 							$this->create($dimFetch, $arrayType->getIterableValueType(), TypeSpecifierContext::createTrue(), $scope),
 						);
+					} elseif ($expr->var instanceof Expr\Variable && is_string($expr->var->name)) {
+						// The array might be empty here, so we cannot register
+						// $arr[$key] unconditionally. Attach a conditional holder
+						// that fires once the user narrows $key to non-null
+						// (e.g. `if ($key !== null)`), giving the deep-write
+						// path the same shape information `isset($arr[$key])`
+						// would have provided.
+						$keyType = $scope->getType($expr->expr);
+						$nonNullKeyType = TypeCombinator::removeNull($keyType);
+						if (!$nonNullKeyType instanceof NeverType && !$keyType->isNull()->yes()) {
+							$dimFetch = new ArrayDimFetch($arrayArg, $expr->var);
+							$dimFetchString = $this->exprPrinter->printExpr($dimFetch);
+							$keyExprString = $this->exprPrinter->printExpr($expr->var);
+
+							$holder = new ConditionalExpressionHolder(
+								[$keyExprString => ExpressionTypeHolder::createYes($expr->var, $nonNullKeyType)],
+								ExpressionTypeHolder::createYes($dimFetch, $arrayType->getIterableValueType()),
+							);
+
+							$specifiedTypes = $specifiedTypes->unionWith(
+								(new SpecifiedTypes([], []))->setNewConditionalExpressionHolders([
+									$dimFetchString => [$holder->getKey() => $holder],
+								]),
+							);
+						}
 					}
 				}
 			}

src/Parser/RichParser.php

@@ -361,7 +361,6 @@ private function parseIdentifiers(string $text, int $ignorePos): array
 			throw new IgnoreParseException('Missing identifier', 1);
 		}
 
-		/** @phpstan-ignore return.type (return type is correct, not sure why it's being changed from array shape to key-value shape) */
 		return $identifiers;
 	}
 

tests/PHPStan/Analyser/nsrt/array-key-last-existing.php

@@ -0,0 +1,63 @@
+<?php declare(strict_types=1);
+
+namespace ArrayKeyLastExisting;
+
+use function PHPStan\Testing\assertType;
+
+/**
+ * Mirrors the RichParser pattern: the array starts empty, gets entries
+ * appended in some loop branches, and an existing entry's nested key is
+ * updated in others. `if ($key !== null)` should be enough to let PHPStan
+ * track that `$arr[$key]` exists and the deep write should preserve the
+ * outer shape, just like `isset($arr[$key])` does.
+ */
+function appendThenUpdateLast(string $name, string $comment): void
+{
+	$identifiers = [];
+	$c = rand(100, 200);
+	for ($i = 0; $i < $c; $i++) {
+		if (rand(0, 1) === 1) {
+			$key = array_key_last($identifiers);
+			if ($key !== null) {
+				$identifiers[$key]['comment'] = $comment;
+			}
+			continue;
+		}
+
+		$identifiers[] = ['name' => $name, 'comment' => null];
+	}
+
+	assertType('list<array{name: string, comment: string|null}>', $identifiers);
+}
+
+function appendThenUpdateFirst(string $name, string $comment): void
+{
+	$identifiers = [];
+	$c = rand(100, 200);
+	for ($i = 0; $i < $c; $i++) {
+		if (rand(0, 1) === 1) {
+			$key = array_key_first($identifiers);
+			if ($key !== null) {
+				$identifiers[$key]['comment'] = $comment;
+			}
+			continue;
+		}
+
+		$identifiers[] = ['name' => $name, 'comment' => null];
+	}
+
+	assertType('list<array{name: string, comment: string|null}>', $identifiers);
+}
+
+/**
+ * @param list<array{name: 'x', comment: null}> $list
+ */
+function maybeEmptyArray(array $list): void
+{
+	$key = array_key_last($list);
+	if ($key !== null) {
+		assertType('array{name: \'x\', comment: null}', $list[$key]);
+		$list[$key]['comment'] = 'hello';
+		assertType('non-empty-list<array{name: \'x\', comment: \'hello\'}>', $list);
+	}
+}