Return the picked keys from array_rand()

array_rand() collapsed the array's key type into int, string or int|string, and
returned `array<int, key>` whenever $num was more than one. Hand back the key
type itself, and build a tuple when $num is a known constant:

    array_rand(['a' => 1, 'b' => 2])   'a'|'b'                 (was string)
    array_rand($list)                  int<0, max>             (was int)
    array_rand($shape, 2)              array{key, key}         (was array<int, key>)
    array_rand($shape, $atLeastTwo)    non-empty-list<key>

An array comes back only when $num is at least 2, since a single pick returns
the key on its own, so the list is non-empty in every branch that produces one.
KEY_COUNT_LIMIT caps the tuple at 100 elements, past which
ConstantArrayTypeBuilder would degrade the shape anyway.

The keys run through castReadKeyType(), so `array<string, X>` gives
`(int|string)` rather than a certain `string`.

array_rand([]) returns never now, which is what PHP 8 does (ValueError). That
also makes everything after the call unreachable, so the two calls in
data/array_rand.php moved into separate functions to keep their diagnostics.

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

Author: zonuexe

src/Type/Php/ArrayRandFunctionReturnTypeExtension.php

@@ -6,21 +6,30 @@
 use PHPStan\Analyser\Scope;
 use PHPStan\DependencyInjection\AutowiredService;
 use PHPStan\Reflection\FunctionReflection;
+use PHPStan\Type\Accessory\AccessoryArrayListType;
+use PHPStan\Type\Accessory\NonEmptyArrayType;
 use PHPStan\Type\ArrayType;
+use PHPStan\Type\Constant\ConstantArrayTypeBuilder;
 use PHPStan\Type\Constant\ConstantIntegerType;
 use PHPStan\Type\DynamicFunctionReturnTypeExtension;
 use PHPStan\Type\IntegerRangeType;
 use PHPStan\Type\IntegerType;
-use PHPStan\Type\StringType;
+use PHPStan\Type\Traverser\UnsafeArrayStringKeyCastingTraverser;
 use PHPStan\Type\Type;
 use PHPStan\Type\TypeCombinator;
-use PHPStan\Type\UnionType;
 use function count;
+use function is_int;
 
 #[AutowiredService]
 final class ArrayRandFunctionReturnTypeExtension implements DynamicFunctionReturnTypeExtension
 {
 
+	/**
+	 * Above this many picked keys the shape stops being worth its cost, and
+	 * ConstantArrayTypeBuilder would degrade it to a general array anyway.
+	 */
+	private const KEY_COUNT_LIMIT = 100;
+
 	public function isFunctionSupported(FunctionReflection $functionReflection): bool
 	{
 		return $functionReflection->getName() === 'array_rand';
@@ -35,34 +44,56 @@ public function getTypeFromFunctionCall(FunctionReflection $functionReflection,
 		}
 
 		$firstArgType = $scope->getType($args[0]->value);
-		$isInteger = $firstArgType->getIterableKeyType()->isInteger();
-		$isString = $firstArgType->getIterableKeyType()->isString();
-
-		if ($isInteger->yes()) {
-			$valueType = new IntegerType();
-		} elseif ($isString->yes()) {
-			$valueType = new StringType();
-		} else {
-			$valueType = new UnionType([new IntegerType(), new StringType()]);
-		}
+		// The picked keys come back as values of their own, so PHP's array key
+		// cast applies to them.
+		$keyType = UnsafeArrayStringKeyCastingTraverser::castReadKeyType($firstArgType->getIterableKeyType());
 
 		if ($argsCount < 2) {
-			return $valueType;
+			return $keyType;
 		}
 
 		$secondArgType = $scope->getType($args[1]->value);
 
 		$one = new ConstantIntegerType(1);
 		if ($one->isSuperTypeOf($secondArgType)->yes()) {
-			return $valueType;
+			return $keyType;
+		}
+
+		$pickedKeys = $this->pickedKeysType($keyType, $secondArgType);
+		if (IntegerRangeType::fromInterval(2, null)->isSuperTypeOf($secondArgType)->yes()) {
+			return $pickedKeys;
 		}
 
-		$bigger2 = IntegerRangeType::fromInterval(2, null);
-		if ($bigger2->isSuperTypeOf($secondArgType)->yes()) {
-			return new ArrayType(new IntegerType(), $valueType);
+		return TypeCombinator::union($keyType, $pickedKeys);
+	}
+
+	/**
+	 * array_rand() picks $num distinct keys and hands them back in the array's
+	 * own order, so a known $num gives an exact tuple. Returning an array at all
+	 * means $num was at least 2 - one key comes back on its own.
+	 */
+	private function pickedKeysType(Type $keyType, Type $numType): Type
+	{
+		$constantNums = $numType->getConstantScalarValues();
+		if (
+			count($constantNums) === 1
+			&& is_int($constantNums[0])
+			&& $constantNums[0] >= 2
+			&& $constantNums[0] <= self::KEY_COUNT_LIMIT
+		) {
+			$builder = ConstantArrayTypeBuilder::createEmpty();
+			for ($i = 0; $i < $constantNums[0]; $i++) {
+				$builder->setOffsetValueType(new ConstantIntegerType($i), $keyType);
+			}
+
+			return $builder->getArray();
 		}
 
-		return TypeCombinator::union($valueType, new ArrayType(new IntegerType(), $valueType));
+		return TypeCombinator::intersect(
+			new ArrayType(new IntegerType(), $keyType),
+			new AccessoryArrayListType(),
+			new NonEmptyArrayType(),
+		);
 	}
 
 }

tests/PHPStan/Analyser/nsrt/array-functions.php

@@ -351,19 +351,19 @@
 assertType('string|null', key($generalStringKeys));
 assertType('int|string|null', key($generalIntegerOrStringKeysMixedValues));
 assertType('\'foo\'', $poppedFoo);
-assertType('int', array_rand([1 => 1, 2 => "2"]));
-assertType('string', array_rand(["a" => 1, "b" => "2"]));
-assertType('int|string', array_rand(["a" => 1, 2 => "b"]));
+assertType('1|2', array_rand([1 => 1, 2 => "2"]));
+assertType('\'a\'|\'b\'', array_rand(["a" => 1, "b" => "2"]));
+assertType('2|\'a\'', array_rand(["a" => 1, 2 => "b"]));
 assertType('int|string', array_rand([1 => 1, 2 => "b", $mixed => $mixed]));
-assertType('int', array_rand([1 => 1, 2 => "b"], 1));
-assertType('string', array_rand(["a" => 1, "b" => "b"], 1));
-assertType('int|string', array_rand(["a" => 1, 2 => "b"], 1));
+assertType('1|2', array_rand([1 => 1, 2 => "b"], 1));
+assertType('\'a\'|\'b\'', array_rand(["a" => 1, "b" => "b"], 1));
+assertType('2|\'a\'', array_rand(["a" => 1, 2 => "b"], 1));
 assertType('int|string', array_rand([1 => 1, 2 => "b", $mixed => $mixed], 1));
-assertType('array<int, int>', array_rand([1 => 1, 2 => "b"], 2));
-assertType('array<int, string>', array_rand(["a" => 1, "b" => "b"], 2));
-assertType('array<int, int|string>', array_rand(["a" => 1, 2 => "b"], 2));
-assertType('array<int, int|string>', array_rand([1 => 1, 2 => "2", $mixed => $mixed], 2));
-assertType('array<int, int>|int', array_rand([1 => 1, 2 => "b"], $mixed));
-assertType('array<int, string>|string', array_rand(["a" => 1, "b" => "b"], $mixed));
-assertType('array<int, int|string>|int|string', array_rand(["a" => 1, 2 => "b"], $mixed));
-assertType('array<int, int|string>|int|string', array_rand([1 => 1, 2 => "b", $mixed => $mixed], $mixed));
+assertType('array{1|2, 1|2}', array_rand([1 => 1, 2 => "b"], 2));
+assertType('array{\'a\'|\'b\', \'a\'|\'b\'}', array_rand(["a" => 1, "b" => "b"], 2));
+assertType('array{2|\'a\', 2|\'a\'}', array_rand(["a" => 1, 2 => "b"], 2));
+assertType('array{int|string, int|string}', array_rand([1 => 1, 2 => "2", $mixed => $mixed], 2));
+assertType('1|2|non-empty-list<1|2>', array_rand([1 => 1, 2 => "b"], $mixed));
+assertType('\'a\'|\'b\'|non-empty-list<\'a\'|\'b\'>', array_rand(["a" => 1, "b" => "b"], $mixed));
+assertType('2|\'a\'|non-empty-list<2|\'a\'>', array_rand(["a" => 1, 2 => "b"], $mixed));
+assertType('int|non-empty-list<int|string>|string', array_rand([1 => 1, 2 => "b", $mixed => $mixed], $mixed));

tests/PHPStan/Analyser/nsrt/array-rand.php

@@ -0,0 +1,39 @@
+<?php
+
+declare(strict_types = 1);
+
+namespace ArrayRandReturnType;
+
+use function PHPStan\Testing\assertType;
+
+/**
+ * @param array{a: 1, b: 2, c: 3} $shape
+ * @param non-empty-list<string> $list
+ * @param non-empty-array<string, int> $strKeyed
+ * @param int<2, max> $atLeastTwo
+ * @param positive-int $positive
+ */
+function f(array $shape, array $list, array $strKeyed, int $atLeastTwo, int $positive, int $int): void
+{
+	assertType("'a'|'b'|'c'", array_rand($shape));
+	assertType("'a'|'b'|'c'", array_rand($shape, 1));
+	assertType("array{'a'|'b'|'c', 'a'|'b'|'c'}", array_rand($shape, 2));
+	assertType("array{'a'|'b'|'c', 'a'|'b'|'c', 'a'|'b'|'c'}", array_rand($shape, 3));
+
+	assertType('int<0, max>', array_rand($list));
+	assertType('array{int<0, max>, int<0, max>}', array_rand($list, 2));
+
+	// a decimal-integer string key comes back as an int, see #15073
+	assertType('(int|string)', array_rand($strKeyed));
+	assertType('array{(int|string), (int|string)}', array_rand($strKeyed, 2));
+
+	// $num is known to be 2 or more, but not by how much
+	assertType("non-empty-list<'a'|'b'|'c'>", array_rand($shape, $atLeastTwo));
+
+	// $num may be 1, which gives back a single key instead of a list
+	assertType("'a'|'b'|'c'|non-empty-list<'a'|'b'|'c'>", array_rand($shape, $positive));
+	assertType("'a'|'b'|'c'|non-empty-list<'a'|'b'|'c'>", array_rand($shape, $int));
+
+	// past KEY_COUNT_LIMIT the shape gives way to a list
+	assertType('non-empty-list<(int|string)>', array_rand($strKeyed, 200));
+}

tests/PHPStan/Rules/Arrays/InvalidKeyInArrayDimFetchRuleTest.php

@@ -157,19 +157,19 @@ public function testBug12981(): void
 	{
 		$this->analyse([__DIR__ . '/data/bug-12981.php'], [
 			[
-				'Invalid array key type array<int, int|string>.',
+				'Invalid array key type array<int, (int|string)>.',
 				31,
 			],
 			[
-				'Invalid array key type array<int, int|string>.',
+				'Invalid array key type array<int, (int|string)>.',
 				33,
 			],
 			[
-				'Possibly invalid array key type array<int, int|string>|int|string.',
+				'Possibly invalid array key type int|list<(int|string)>|string.',
 				39,
 			],
 			[
-				'Possibly invalid array key type array<int, int|string>|int|string.',
+				'Possibly invalid array key type int|list<(int|string)>|string.',
 				41,
 			],
 		]);

tests/PHPStan/Rules/Arrays/NonexistentOffsetInArrayDimFetchRuleTest.php

@@ -977,11 +977,11 @@ public function testBug12981(): void
 
 		$this->analyse([__DIR__ . '/data/bug-12981.php'], [
 			[
-				'Offset array<int, int|string>|int|string might not exist on non-empty-array<bool|float|int|string>.',
+				'Offset int|non-empty-list<(int|string)>|string might not exist on non-empty-array<bool|float|int|string>.',
 				39,
 			],
 			[
-				'Offset array<int, int|string>|int|string might not exist on non-empty-array<bool|float|int|string>.',
+				'Offset int|non-empty-list<(int|string)>|string might not exist on non-empty-array<bool|float|int|string>.',
 				41,
 			],
 		]);

tests/PHPStan/Rules/Functions/CallToFunctionParametersRuleTest.php

@@ -2528,20 +2528,20 @@ public function testArrayRand(): void
 			],
 			[
 				'Parameter #1 $input of function array_rand expects non-empty-array, array{} given.',
-				8,
+				14,
 				'array{} is empty.',
 			],
 			[
 				'Parameter #2 $num_req of function array_rand expects int<1, max>, int given.',
-				8,
+				14,
 			],
 			[
 				'Parameter #2 $num_req of function array_rand expects int<1, max>, -5 given.',
-				13,
+				19,
 			],
 			[
 				'Parameter #2 $num_req of function array_rand expects int<1, max>, 0 given.',
-				14,
+				20,
 			],
 		]);
 	}

tests/PHPStan/Rules/Functions/data/array_rand.php

@@ -2,9 +2,15 @@
 
 namespace ArrayRand;
 
-function doFoo(int $i) {
+function doFoo() {
 	$arr = [];
 	$x = array_rand($arr);
+}
+
+// array_rand() on an empty array never returns, so this needs its own function
+// to stay reachable.
+function doFooWithNum(int $i) {
+	$arr = [];
 	$y = array_rand($arr, $i);
 }
 

tests/PHPStan/Rules/Functions/data/bug-9803.php

@@ -13,16 +13,16 @@ function doFoo() {
 	$keys = array();
 	if ($random == 1) {
 		$keys = array(array_rand($array));
-		assertType('array{int}', $keys);
+		assertType('array{0|1|2|3|4|5|6|7|8|9}', $keys);
 	}
 	else {
 		$keys = array_rand($array, $random);
-		assertType('array<int, int>', $keys);
+		assertType('non-empty-list<0|1|2|3|4|5|6|7|8|9>', $keys);
 	}
 
-	assertType('array<int, int>', $keys);
+	assertType('non-empty-list<0|1|2|3|4|5|6|7|8|9>', $keys);
 	$theKeys = array_keys($keys);
-	assertType('list<int>', $theKeys);
+	assertType('non-empty-list<int<0, max>>', $theKeys);
 }