Cast array keys that are handed back as values

PHP casts a decimal-integer string array key ("123") to int, so
`array_key_first([$string => null])` is not necessarily a string. PHPStan
inferred `string` for it and reported `is_int()` on the result as always false.

array_key_first() and array_key_last() went first; call castReadKeyType() from
the rest of the accessors that hand a key back as a value of its own:
array_keys(), key(), array_find_key(), array_search() and the values of
array_flip().

`foreach` keys stay unwidened with the toggle off: the key usually goes straight
back into another array, and a benevolent `(int|string)` key collapses that
array to `array<mixed, …>`. `detect` remains the level with accurate `foreach`
keys.

The rename in OptimizedDirectorySourceLocatorFactory is fallout: with the wider
`array_keys()` type PHPStan now proves `$file` defined inside
`if ($findInFiles !== [])`, which is correct and makes strict-rules flag the
reuse.

The `@var int|string` workarounds over `key([$string => null])` in
ArgumentsNormalizer and ConstantStringType are what this bug looks like from the
inside; both are redundant now and go away with their baseline entries.

Closes phpstan/phpstan#15073

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>

Author: zonuexe

phpstan-baseline.neon

@@ -12,12 +12,6 @@ parameters:
 			count: 1
 			path: src/Analyser/AnalyserResultFinalizer.php
 
-		-
-			rawMessage: PHPDoc tag @var with type int|string is not subtype of type string.
-			identifier: varTag.type
-			count: 1
-			path: src/Analyser/ArgumentsNormalizer.php
-
 		-
 			rawMessage: Casting to string something that's already string.
 			identifier: cast.useless
@@ -1053,12 +1047,6 @@ parameters:
 			count: 1
 			path: src/Type/Constant/ConstantStringType.php
 
-		-
-			rawMessage: PHPDoc tag @var with type int|string is not subtype of type string.
-			identifier: varTag.type
-			count: 1
-			path: src/Type/Constant/ConstantStringType.php
-
 		-
 			rawMessage: 'Doing instanceof PHPStan\Type\Constant\ConstantArrayType is error-prone and deprecated. Use Type::getConstantArrays() instead.'
 			identifier: phpstanApi.instanceofType

src/Analyser/ArgumentsNormalizer.php

@@ -149,7 +149,6 @@ public static function reorderCallUserFuncArrayArguments(
 		foreach ($argsArrayArg->value->items as $item) {
 			$key = null;
 			if ($item->key instanceof String_) {
-				/** @var int|string $key */
 				$key = key([$item->key->value => null]);
 				if ($key === '') {
 					return null;

src/Reflection/BetterReflection/SourceLocator/OptimizedDirectorySourceLocatorFactory.php

@@ -213,9 +213,9 @@ private function createCachedDirectorySourceLocator(array $fileHashes, string $c
 
 			if ($findInFiles !== []) {
 				$cacheModified = true;
-				foreach ($this->symbolFinderInFiles->findSymbols($findInFiles, $this->phpVersion->supportsEnums()) as $file => [$newClasses, $newFunctions, $newConstants]) {
-					$newHash = $originalFileHashes[$file];
-					$cached[$file] = [$newHash, $newClasses, $newFunctions, $newConstants];
+				foreach ($this->symbolFinderInFiles->findSymbols($findInFiles, $this->phpVersion->supportsEnums()) as $scannedFile => [$newClasses, $newFunctions, $newConstants]) {
+					$newHash = $originalFileHashes[$scannedFile];
+					$cached[$scannedFile] = [$newHash, $newClasses, $newFunctions, $newConstants];
 				}
 			}
 

src/Type/ArrayType.php

@@ -222,7 +222,7 @@ public function getKeysArrayFiltered(Type $filterValueType, TrinaryLogic $strict
 
 	public function getKeysArray(): Type
 	{
-		return TypeCombinator::intersect(new self(new IntegerType(), $this->getIterableKeyType()), new AccessoryArrayListType());
+		return TypeCombinator::intersect(new self(new IntegerType(), UnsafeArrayStringKeyCastingTraverser::castReadKeyType($this->getIterableKeyType())), new AccessoryArrayListType());
 	}
 
 	public function getValuesArray(): Type
@@ -505,7 +505,8 @@ public function fillKeysArray(Type $valueType): Type
 
 	public function flipArray(): Type
 	{
-		return new self($this->getIterableValueType()->toArrayKey(), $this->getIterableKeyType());
+		// The keys become values, so they're subject to PHP's array key cast.
+		return new self($this->getIterableValueType()->toArrayKey(), UnsafeArrayStringKeyCastingTraverser::castReadKeyType($this->getIterableKeyType()));
 	}
 
 	public function intersectKeyArray(Type $otherArraysType): Type
@@ -587,7 +588,7 @@ public function searchArray(Type $needleType, ?TrinaryLogic $strict = null): Typ
 			return new ConstantBooleanType(false);
 		}
 
-		return TypeCombinator::union($this->getIterableKeyType(), new ConstantBooleanType(false));
+		return UnsafeArrayStringKeyCastingTraverser::unionWithReadKeyType($this->getIterableKeyType(), new ConstantBooleanType(false));
 	}
 
 	public function shiftArray(): Type

src/Type/Constant/ConstantArrayType.php

@@ -1602,15 +1602,16 @@ public function flipArray(): Type
 			$offsetType = $valueType->toArrayKey();
 			$builder->setOffsetValueType(
 				$offsetType,
-				$keyType,
+				// The keys become values, so they're subject to PHP's array key cast.
+				UnsafeArrayStringKeyCastingTraverser::castReadKeyType($keyType),
 				$this->isOptionalKey($i) || count($offsetType->getConstantScalarTypes()) > 1,
 			);
 		}
 
 		if ($this->isUnsealed()->yes() && $this->unsealed !== null) {
 			[$unsealedKey, $unsealedValue] = $this->unsealed;
 			$flippedKey = $unsealedValue->toArrayKey();
-			$flippedValue = $unsealedKey;
+			$flippedValue = UnsafeArrayStringKeyCastingTraverser::castReadKeyType($unsealedKey);
 			// For a non-finite tail key (e.g. `string`), install the
 			// unsealed extras first; setOffsetValueType then widens any
 			// overlapping explicit values with the tail's value type.
@@ -1731,11 +1732,14 @@ public function searchArray(Type $needleType, ?TrinaryLogic $strict = null): Typ
 		}
 
 		if (count($matches) > 0) {
+			// The found key becomes a value of its own, so it's subject to PHP's
+			// array key cast.
+			$matchedKeyType = TypeCombinator::union(...$matches);
 			if ($hasIdenticalValue) {
-				return TypeCombinator::union(...$matches);
+				return UnsafeArrayStringKeyCastingTraverser::castReadKeyType($matchedKeyType);
 			}
 
-			return TypeCombinator::union(new ConstantBooleanType(false), ...$matches);
+			return UnsafeArrayStringKeyCastingTraverser::unionWithReadKeyType($matchedKeyType, new ConstantBooleanType(false));
 		}
 
 		return new ConstantBooleanType(false);
@@ -2443,7 +2447,7 @@ private function degradeToGeneralArray(): Type
 
 	public function getKeysArrayFiltered(Type $filterValueType, TrinaryLogic $strict): Type
 	{
-		$keysArray = $this->getKeysOrValuesArray($this->keyTypes, $this->unsealed[0] ?? null);
+		$keysArray = $this->getReadKeysArray();
 
 		return new IntersectionType([
 			new ArrayType(
@@ -2456,7 +2460,24 @@ public function getKeysArrayFiltered(Type $filterValueType, TrinaryLogic $strict
 
 	public function getKeysArray(): self
 	{
-		return $this->getKeysOrValuesArray($this->keyTypes, $this->unsealed[0] ?? null);
+		return $this->getReadKeysArray();
+	}
+
+	/**
+	 * The keys as a list of values - they've left the array, so they're subject
+	 * to PHP's array key cast.
+	 */
+	private function getReadKeysArray(): self
+	{
+		$unsealedKeyType = $this->unsealed[0] ?? null;
+
+		return $this->getKeysOrValuesArray(
+			array_map(
+				static fn (Type $keyType): Type => UnsafeArrayStringKeyCastingTraverser::castReadKeyType($keyType),
+				$this->keyTypes,
+			),
+			$unsealedKeyType !== null ? UnsafeArrayStringKeyCastingTraverser::castReadKeyType($unsealedKeyType) : null,
+		);
 	}
 
 	public function getValuesArray(): self

src/Type/Constant/ConstantStringType.php

@@ -385,7 +385,6 @@ public function toArrayKey(): Type
 			return $this->arrayKeyType;
 		}
 
-		/** @var int|string $offsetValue */
 		$offsetValue = key([$this->value => null]);
 
 		if ($offsetValue === $this->value) {

src/Type/Php/ArrayFindKeyFunctionReturnTypeExtension.php

@@ -8,8 +8,8 @@
 use PHPStan\Reflection\FunctionReflection;
 use PHPStan\Type\DynamicFunctionReturnTypeExtension;
 use PHPStan\Type\NullType;
+use PHPStan\Type\Traverser\UnsafeArrayStringKeyCastingTraverser;
 use PHPStan\Type\Type;
-use PHPStan\Type\TypeCombinator;
 use function count;
 
 #[AutowiredService]
@@ -33,7 +33,7 @@ public function getTypeFromFunctionCall(FunctionReflection $functionReflection,
 			return null;
 		}
 
-		return TypeCombinator::union($arrayType->getIterableKeyType(), new NullType());
+		return UnsafeArrayStringKeyCastingTraverser::unionWithReadKeyType($arrayType->getIterableKeyType(), new NullType());
 	}
 
 }

src/Type/Php/ArrayKeyDynamicReturnTypeExtension.php

@@ -8,8 +8,8 @@
 use PHPStan\Reflection\FunctionReflection;
 use PHPStan\Type\DynamicFunctionReturnTypeExtension;
 use PHPStan\Type\NullType;
+use PHPStan\Type\Traverser\UnsafeArrayStringKeyCastingTraverser;
 use PHPStan\Type\Type;
-use PHPStan\Type\TypeCombinator;
 
 #[AutowiredService]
 final class ArrayKeyDynamicReturnTypeExtension implements DynamicFunctionReturnTypeExtension
@@ -35,10 +35,10 @@ public function getTypeFromFunctionCall(FunctionReflection $functionReflection,
 
 		$keyType = $argType->getIterableKeyType();
 		if ($iterableAtLeastOnce->yes()) {
-			return $keyType;
+			return UnsafeArrayStringKeyCastingTraverser::castReadKeyType($keyType);
 		}
 
-		return TypeCombinator::union($keyType, new NullType());
+		return UnsafeArrayStringKeyCastingTraverser::unionWithReadKeyType($keyType, new NullType());
 	}
 
 }

tests/PHPStan/Analyser/data/report-unsafe-array-string-key-casting-detect.php

@@ -127,3 +127,25 @@ public function doBaz(array $a): void
 	}
 
 }
+
+class ReadKeys
+{
+
+	/**
+	 * @param array<string, int> $a
+	 * @param non-empty-array<string, int> $b
+	 */
+	public function doFoo(array $a, array $b, string $s): void
+	{
+		assertType('int|non-decimal-int-string', array_key_first([$s => null]));
+		assertType('int|non-decimal-int-string', array_key_last([$s => null]));
+		assertType('non-empty-list<int|non-decimal-int-string>', array_keys([$s => null]));
+
+		assertType('int|non-decimal-int-string|null', array_key_first($a));
+		assertType('int|non-decimal-int-string', array_key_last($b));
+		assertType('list<int|non-decimal-int-string>', array_keys($a));
+		assertType('int|non-decimal-int-string|null', key($a));
+		assertType('int|non-decimal-int-string|false', array_search(1, $a, true));
+	}
+
+}

tests/PHPStan/Analyser/nsrt/array-find-key.php

@@ -33,8 +33,8 @@ function array_find_key(array $array, callable $callback)
 	 */
 	function testMixed(array $array, callable $callback): void
 	{
-		assertType('int|string|null', array_find_key($array, $callback));
-		assertType('int|string|null', array_find_key($array, 'is_int'));
+		assertType('(int|string|null)', array_find_key($array, $callback));
+		assertType('(int|string|null)', array_find_key($array, 'is_int'));
 	}
 
 	/**