Widen the key type of functions that return an array key

[zonuexe]

Closes phpstan/phpstan#15073

Continues the numeric-string / decimal-int-string consistency work of #3326, phpstan/phpstan#6847 and #5328.

Problem

PHP casts a decimal-integer string array key ("123") to int, so a key read out of an array
with a string key type can be an int:

function is_decimal_int_string(mixed $val): bool {
    return is_string($val) && is_int(array_key_first([ $val => null ]));
    // Call to function is_int() with string will always evaluate to false.
}

array_key_last(), array_keys()[0], key(), array_find_key(), array_search() and the values of array_flip() have the same problem.

Change

UnsafeArrayStringKeyCastingTraverser already models this cast for the key type an array has. That type also drives describe(), accepts() and type subtraction, which is why only reportUnsafeArrayStringKeyCasting: detect widens it. I tried widening it with the toggle off: array<string, X> turns into array<X> everywhere and 113 tests fail, including mixed~array<string, mixed> losing every array.

So this adds a second entry point, for keys that leave the array as a value:

method	widens	toggle off	detect
castKeyType()	the key type an array has	nothing	int|non-decimal-int-string
castReadKeyType()	a key returned as a value	(int|string)	same
unionWithReadKeyType()	the above, plus the null/false for an empty array	keeps the union benevolent	same

The benevolent union keeps new errors out: is_int($key) reports maybe instead of "always false", and strlen($key) still passes. unionWithReadKeyType() exists because TypeCombinator::union() drops the benevolence, which would break strlen(array_key_first($a) ?? '') on a possibly empty array<string, …>.

assertType('(int|string)', array_key_first([$string => null]));            // was: string
assertType('non-empty-list<(int|string)>', array_keys([$string => null])); // was: non-empty-list<string>
assertType('int', array_key_first([$decimal_string => null]));
assertType('non-decimal-int-string', array_key_first([$non_decimal_string => null]));

Left alone

• foreach keys, with the toggle off. You write $result[$k] = … right after, and a benevolent (int|string) key turns that array into array<mixed, …>. Six nsrt files lose their key type that way. Use detect for accurate foreach keys.
• The key type of arrays that array_flip() and array_fill_keys() build. They keep the raw string, and reading a key back out of them runs the new cast anyway.
• array_rand(). Same bug, but its result collapses to int|string by construction, so strlen(array_rand($stringKeyed)) would start failing. Separate PR.

Also in here

The first two commits stand on their own:

• fillKeysArray() on a general array only called toString(), so array_fill_keys() disagreed with array_flip() next to it.
• getIterableKeyType(), getFirstIterableKeyType() and getLastIterableKeyType() repeated the same unsealed-tail normalization, and the first/last pair missed the detect cast.

Two more things ride along in the third commit. The @var int|string over key([$string => null]) in ArgumentsNormalizer and ConstantStringType covered for this bug; both are gone, with their baseline entries. The $file rename in OptimizedDirectorySourceLocatorFactory is fallout: PHPStan now proves $file defined inside if ($findInFiles !== []), so strict-rules flags the reuse.

Tests

nsrt/bug-15073.php is new and fails on 8 assertions without the src/ change. The detect fixture gets read-key cases. Other expectation updates come in two shapes: int|string|null to (int|string|null) where the benevolence survives now, and string to (int|string) where the fix applies.