More precise array_keys return type

staabm · web-flow · commit cdf4b4df4825 · 2025-07-17T16:52:08.000+02:00
diff --git a/src/Type/Accessory/AccessoryArrayListType.php b/src/Type/Accessory/AccessoryArrayListType.php
@@ -172,6 +172,11 @@ public function unsetOffset(Type $offsetType): Type
 		return new ErrorType();
 	}
 
+	public function getKeysArrayFiltered(Type $filterValueType, TrinaryLogic $strict): Type
+	{
+		return $this->getKeysArray();
+	}
+
 	public function getKeysArray(): Type
 	{
 		return $this;
diff --git a/src/Type/Accessory/HasOffsetType.php b/src/Type/Accessory/HasOffsetType.php
@@ -352,6 +352,11 @@ public function looseCompare(Type $type, PhpVersion $phpVersion): BooleanType
 		return new BooleanType();
 	}
 
+	public function getKeysArrayFiltered(Type $filterValueType, TrinaryLogic $strict): Type
+	{
+		return $this->getKeysArray();
+	}
+
 	public function getKeysArray(): Type
 	{
 		return new NonEmptyArrayType();
diff --git a/src/Type/Accessory/HasOffsetValueType.php b/src/Type/Accessory/HasOffsetValueType.php
@@ -195,6 +195,11 @@ public function unsetOffset(Type $offsetType): Type
 		return $this;
 	}
 
+	public function getKeysArrayFiltered(Type $filterValueType, TrinaryLogic $strict): Type
+	{
+		return $this->getKeysArray();
+	}
+
 	public function getKeysArray(): Type
 	{
 		return new NonEmptyArrayType();
diff --git a/src/Type/Accessory/NonEmptyArrayType.php b/src/Type/Accessory/NonEmptyArrayType.php
@@ -159,6 +159,11 @@ public function unsetOffset(Type $offsetType): Type
 		return new ErrorType();
 	}
 
+	public function getKeysArrayFiltered(Type $filterValueType, TrinaryLogic $strict): Type
+	{
+		return $this->getKeysArray();
+	}
+
 	public function getKeysArray(): Type
 	{
 		return $this;
diff --git a/src/Type/Accessory/OversizedArrayType.php b/src/Type/Accessory/OversizedArrayType.php
@@ -154,6 +154,11 @@ public function unsetOffset(Type $offsetType): Type
 		return new ErrorType();
 	}
 
+	public function getKeysArrayFiltered(Type $filterValueType, TrinaryLogic $strict): Type
+	{
+		return $this->getKeysArray();
+	}
+
 	public function getKeysArray(): Type
 	{
 		return $this;
diff --git a/src/Type/ArrayType.php b/src/Type/ArrayType.php
@@ -170,6 +170,11 @@ public function generalizeValues(): self
 		return new self($this->keyType, $this->itemType->generalize(GeneralizePrecision::lessSpecific()));
 	}
 
+	public function getKeysArrayFiltered(Type $filterValueType, TrinaryLogic $strict): Type
+	{
+		return $this->getKeysArray();
+	}
+
 	public function getKeysArray(): Type
 	{
 		return TypeCombinator::intersect(new self(new IntegerType(), $this->getIterableKeyType()), new AccessoryArrayListType());
diff --git a/src/Type/Constant/ConstantArrayType.php b/src/Type/Constant/ConstantArrayType.php
@@ -35,6 +35,7 @@
 use PHPStan\Type\Generic\TemplateTypeMap;
 use PHPStan\Type\Generic\TemplateTypeVariance;
 use PHPStan\Type\IntegerRangeType;
+use PHPStan\Type\IntegerType;
 use PHPStan\Type\IntersectionType;
 use PHPStan\Type\IsSuperTypeOfResult;
 use PHPStan\Type\MixedType;
@@ -1372,6 +1373,19 @@ private function degradeToGeneralArray(): Type
 		return $builder->getArray();
 	}
 
+	public function getKeysArrayFiltered(Type $filterValueType, TrinaryLogic $strict): Type
+	{
+		$keysArray = $this->getKeysOrValuesArray($this->keyTypes);
+
+		return TypeCombinator::intersect(
+			new ArrayType(
+				new IntegerType(),
+				$keysArray->getIterableValueType(),
+			),
+			new AccessoryArrayListType(),
+		);
+	}
+
 	public function getKeysArray(): self
 	{
 		return $this->getKeysOrValuesArray($this->keyTypes);
diff --git a/src/Type/IntersectionType.php b/src/Type/IntersectionType.php
@@ -842,6 +842,11 @@ public function unsetOffset(Type $offsetType): Type
 		return $this->intersectTypes(static fn (Type $type): Type => $type->unsetOffset($offsetType));
 	}
 
+	public function getKeysArrayFiltered(Type $filterValueType, TrinaryLogic $strict): Type
+	{
+		return $this->intersectTypes(static fn (Type $type): Type => $type->getKeysArrayFiltered($filterValueType, $strict));
+	}
+
 	public function getKeysArray(): Type
 	{
 		return $this->intersectTypes(static fn (Type $type): Type => $type->getKeysArray());
diff --git a/src/Type/MixedType.php b/src/Type/MixedType.php
@@ -180,6 +180,11 @@ public function unsetOffset(Type $offsetType): Type
 		return $this;
 	}
 
+	public function getKeysArrayFiltered(Type $filterValueType, TrinaryLogic $strict): Type
+	{
+		return $this->getKeysArray();
+	}
+
 	public function getKeysArray(): Type
 	{
 		if ($this->isArray()->no()) {
diff --git a/src/Type/NeverType.php b/src/Type/NeverType.php
@@ -273,6 +273,11 @@ public function unsetOffset(Type $offsetType): Type
 		return new NeverType();
 	}
 
+	public function getKeysArrayFiltered(Type $filterValueType, TrinaryLogic $strict): Type
+	{
+		return $this->getKeysArray();
+	}
+
 	public function getKeysArray(): Type
 	{
 		return new NeverType();
diff --git a/src/Type/Php/ArrayKeysFunctionDynamicReturnTypeExtension.php b/src/Type/Php/ArrayKeysFunctionDynamicReturnTypeExtension.php
@@ -7,6 +7,7 @@
 use PHPStan\DependencyInjection\AutowiredService;
 use PHPStan\Php\PhpVersion;
 use PHPStan\Reflection\FunctionReflection;
+use PHPStan\TrinaryLogic;
 use PHPStan\Type\DynamicFunctionReturnTypeExtension;
 use PHPStan\Type\NeverType;
 use PHPStan\Type\NullType;
@@ -29,15 +30,27 @@ public function isFunctionSupported(FunctionReflection $functionReflection): boo
 
 	public function getTypeFromFunctionCall(FunctionReflection $functionReflection, FuncCall $functionCall, Scope $scope): ?Type
 	{
-		if (count($functionCall->getArgs()) !== 1) {
+		$args = $functionCall->getArgs();
+		if (count($args) < 1) {
 			return null;
 		}
 
-		$arrayType = $scope->getType($functionCall->getArgs()[0]->value);
+		$arrayType = $scope->getType($args[0]->value);
 		if ($arrayType->isArray()->no()) {
 			return $this->phpVersion->arrayFunctionsReturnNullWithNonArray() ? new NullType() : new NeverType();
 		}
 
+		if (count($args) >= 2) {
+			$filterType = $scope->getType($args[1]->value);
+
+			$strict = TrinaryLogic::createNo();
+			if (count($args) >= 3) {
+				$strict = $scope->getType($args[2]->value)->isTrue();
+			}
+
+			return $arrayType->getKeysArrayFiltered($filterType, $strict);
+		}
+
 		return $arrayType->getKeysArray();
 	}
 
diff --git a/src/Type/StaticType.php b/src/Type/StaticType.php
@@ -395,6 +395,11 @@ public function unsetOffset(Type $offsetType): Type
 		return $this->getStaticObjectType()->unsetOffset($offsetType);
 	}
 
+	public function getKeysArrayFiltered(Type $filterValueType, TrinaryLogic $strict): Type
+	{
+		return $this->getStaticObjectType()->getKeysArrayFiltered($filterValueType, $strict);
+	}
+
 	public function getKeysArray(): Type
 	{
 		return $this->getStaticObjectType()->getKeysArray();
diff --git a/src/Type/Traits/LateResolvableTypeTrait.php b/src/Type/Traits/LateResolvableTypeTrait.php
@@ -248,6 +248,11 @@ public function unsetOffset(Type $offsetType): Type
 		return $this->resolve()->unsetOffset($offsetType);
 	}
 
+	public function getKeysArrayFiltered(Type $filterValueType, TrinaryLogic $strict): Type
+	{
+		return $this->resolve()->getKeysArrayFiltered($filterValueType, $strict);
+	}
+
 	public function getKeysArray(): Type
 	{
 		return $this->resolve()->getKeysArray();
diff --git a/src/Type/Traits/MaybeArrayTypeTrait.php b/src/Type/Traits/MaybeArrayTypeTrait.php
@@ -39,6 +39,11 @@ public function isList(): TrinaryLogic
 		return TrinaryLogic::createMaybe();
 	}
 
+	public function getKeysArrayFiltered(Type $filterValueType, TrinaryLogic $strict): Type
+	{
+		return $this->getKeysArray();
+	}
+
 	public function getKeysArray(): Type
 	{
 		return new ErrorType();
diff --git a/src/Type/Traits/NonArrayTypeTrait.php b/src/Type/Traits/NonArrayTypeTrait.php
@@ -39,6 +39,11 @@ public function isList(): TrinaryLogic
 		return TrinaryLogic::createNo();
 	}
 
+	public function getKeysArrayFiltered(Type $filterValueType, TrinaryLogic $strict): Type
+	{
+		return $this->getKeysArray();
+	}
+
 	public function getKeysArray(): Type
 	{
 		return new ErrorType();
diff --git a/src/Type/Type.php b/src/Type/Type.php
@@ -134,6 +134,8 @@ public function setExistingOffsetValueType(Type $offsetType, Type $valueType): T
 
 	public function unsetOffset(Type $offsetType): Type;
 
+	public function getKeysArrayFiltered(Type $filterValueType, TrinaryLogic $strict): Type;
+
 	public function getKeysArray(): Type;
 
 	public function getValuesArray(): Type;
diff --git a/src/Type/UnionType.php b/src/Type/UnionType.php
@@ -731,6 +731,11 @@ public function unsetOffset(Type $offsetType): Type
 		return $this->unionTypes(static fn (Type $type): Type => $type->unsetOffset($offsetType));
 	}
 
+	public function getKeysArrayFiltered(Type $filterValueType, TrinaryLogic $strict): Type
+	{
+		return $this->unionTypes(static fn (Type $type): Type => $type->getKeysArrayFiltered($filterValueType, $strict));
+	}
+
 	public function getKeysArray(): Type
 	{
 		return $this->unionTypes(static fn (Type $type): Type => $type->getKeysArray());
diff --git a/tests/PHPStan/Analyser/nsrt/bug-11928.php b/tests/PHPStan/Analyser/nsrt/bug-11928.php
@@ -0,0 +1,68 @@
+<?php
+
+namespace Bug11928;
+
+use function PHPStan\Testing\assertType;
+
+function doFoo()
+{
+	$a = [2 => 1, 3 => 2, 4 => 1];
+
+	$keys = array_keys($a, 1); // returns [2, 4]
+	assertType('list<2|3|4>', $keys);
+
+	$keys = array_keys($a); // returns [2, 3, 4]
+	assertType('array{2, 3, 4}', $keys);
+}
+
+/**
+ * @param array<1|2|3, 4|5|6> $unionKeyedArray
+ * @param 4|5 $fourOrFive
+ * @return void
+ */
+function doFooStrings($unionKeyedArray, $fourOrFive) {
+	$a = [2 => 'hi', 3 => '123', 'xy' => 5];
+	$keys = array_keys($a, 1);
+	assertType("list<2|3|'xy'>", $keys);
+
+	$keys = array_keys($a);
+	assertType("array{2, 3, 'xy'}", $keys);
+
+	$keys = array_keys($unionKeyedArray, 1);
+	assertType("list<1|2|3>", $keys); // could be array{}
+
+	$keys = array_keys($unionKeyedArray, 4);
+	assertType("list<1|2|3>", $keys);
+
+	$keys = array_keys($unionKeyedArray, $fourOrFive);
+	assertType("list<1|2|3>", $keys);
+
+	$keys = array_keys($unionKeyedArray);
+	assertType("list<1|2|3>", $keys);
+}
+
+/**
+ * @param array<int, int> $array
+ * @param list<int> $list
+ * @param array<string, string> $strings
+ * @return void
+ */
+function doFooBar(array $array, array $list, array $strings) {
+	$keys = array_keys($strings, "a", true);
+	assertType('list<string>', $keys);
+
+	$keys = array_keys($strings, "a", false);
+	assertType('list<string>', $keys);
+
+	$keys = array_keys($array, 1, true);
+	assertType('list<int>', $keys);
+
+	$keys = array_keys($array, 1, false);
+	assertType('list<int>', $keys);
+
+	$keys = array_keys($list, 1, true);
+	assertType('list<int<0, max>>', $keys);
+
+	$keys = array_keys($list, 1, true);
+	assertType('list<int<0, max>>', $keys);
+}

Original file line number	Diff line number	Diff line change
`@@ -172,6 +172,11 @@ public function unsetOffset(Type $offsetType): Type`
`172`	`172`	`return new ErrorType();`
`173`	`173`	`}`
`174`	`174`
	`175`	`+ public function getKeysArrayFiltered(Type $filterValueType, TrinaryLogic $strict): Type`
	`176`	`+ {`
	`177`	`+ return $this->getKeysArray();`
	`178`	`+ }`
	`179`	`+`
`175`	`180`	`public function getKeysArray(): Type`
`176`	`181`	`{`
`177`	`182`	`return $this;`
Original file line number	Diff line number	Diff line change
`@@ -352,6 +352,11 @@ public function looseCompare(Type $type, PhpVersion $phpVersion): BooleanType`
`352`	`352`	`return new BooleanType();`
`353`	`353`	`}`
`354`	`354`
	`355`	`+ public function getKeysArrayFiltered(Type $filterValueType, TrinaryLogic $strict): Type`
	`356`	`+ {`
	`357`	`+ return $this->getKeysArray();`
	`358`	`+ }`
	`359`	`+`
`355`	`360`	`public function getKeysArray(): Type`
`356`	`361`	`{`
`357`	`362`	`return new NonEmptyArrayType();`
Original file line number	Diff line number	Diff line change
`@@ -195,6 +195,11 @@ public function unsetOffset(Type $offsetType): Type`
`195`	`195`	`return $this;`
`196`	`196`	`}`
`197`	`197`
	`198`	`+ public function getKeysArrayFiltered(Type $filterValueType, TrinaryLogic $strict): Type`
	`199`	`+ {`
	`200`	`+ return $this->getKeysArray();`
	`201`	`+ }`
	`202`	`+`
`198`	`203`	`public function getKeysArray(): Type`
`199`	`204`	`{`
`200`	`205`	`return new NonEmptyArrayType();`
Original file line number	Diff line number	Diff line change
`@@ -159,6 +159,11 @@ public function unsetOffset(Type $offsetType): Type`
`159`	`159`	`return new ErrorType();`
`160`	`160`	`}`
`161`	`161`
	`162`	`+ public function getKeysArrayFiltered(Type $filterValueType, TrinaryLogic $strict): Type`
	`163`	`+ {`
	`164`	`+ return $this->getKeysArray();`
	`165`	`+ }`
	`166`	`+`
`162`	`167`	`public function getKeysArray(): Type`
`163`	`168`	`{`
`164`	`169`	`return $this;`
Original file line number	Diff line number	Diff line change
`@@ -154,6 +154,11 @@ public function unsetOffset(Type $offsetType): Type`
`154`	`154`	`return new ErrorType();`
`155`	`155`	`}`
`156`	`156`
	`157`	`+ public function getKeysArrayFiltered(Type $filterValueType, TrinaryLogic $strict): Type`
	`158`	`+ {`
	`159`	`+ return $this->getKeysArray();`
	`160`	`+ }`
	`161`	`+`
`157`	`162`	`public function getKeysArray(): Type`
`158`	`163`	`{`
`159`	`164`	`return $this;`
Original file line number	Diff line number	Diff line change
`@@ -170,6 +170,11 @@ public function generalizeValues(): self`
`170`	`170`	`return new self($this->keyType, $this->itemType->generalize(GeneralizePrecision::lessSpecific()));`
`171`	`171`	`}`
`172`	`172`
	`173`	`+ public function getKeysArrayFiltered(Type $filterValueType, TrinaryLogic $strict): Type`
	`174`	`+ {`
	`175`	`+ return $this->getKeysArray();`
	`176`	`+ }`
	`177`	`+`
`173`	`178`	`public function getKeysArray(): Type`
`174`	`179`	`{`
`175`	`180`	`return TypeCombinator::intersect(new self(new IntegerType(), $this->getIterableKeyType()), new AccessoryArrayListType());`
Original file line number	Diff line number	Diff line change
`@@ -842,6 +842,11 @@ public function unsetOffset(Type $offsetType): Type`
`842`	`842`	`return $this->intersectTypes(static fn (Type $type): Type => $type->unsetOffset($offsetType));`
`843`	`843`	`}`
`844`	`844`
	`845`	`+ public function getKeysArrayFiltered(Type $filterValueType, TrinaryLogic $strict): Type`
	`846`	`+ {`
	`847`	`+ return $this->intersectTypes(static fn (Type $type): Type => $type->getKeysArrayFiltered($filterValueType, $strict));`
	`848`	`+ }`
	`849`	`+`
`845`	`850`	`public function getKeysArray(): Type`
`846`	`851`	`{`
`847`	`852`	`return $this->intersectTypes(static fn (Type $type): Type => $type->getKeysArray());`
Original file line number	Diff line number	Diff line change
`@@ -180,6 +180,11 @@ public function unsetOffset(Type $offsetType): Type`
`180`	`180`	`return $this;`
`181`	`181`	`}`
`182`	`182`
	`183`	`+ public function getKeysArrayFiltered(Type $filterValueType, TrinaryLogic $strict): Type`
	`184`	`+ {`
	`185`	`+ return $this->getKeysArray();`
	`186`	`+ }`
	`187`	`+`
`183`	`188`	`public function getKeysArray(): Type`
`184`	`189`	`{`
`185`	`190`	`if ($this->isArray()->no()) {`
Original file line number	Diff line number	Diff line change
`@@ -273,6 +273,11 @@ public function unsetOffset(Type $offsetType): Type`
`273`	`273`	`return new NeverType();`
`274`	`274`	`}`
`275`	`275`
	`276`	`+ public function getKeysArrayFiltered(Type $filterValueType, TrinaryLogic $strict): Type`
	`277`	`+ {`
	`278`	`+ return $this->getKeysArray();`
	`279`	`+ }`
	`280`	`+`
`276`	`281`	`public function getKeysArray(): Type`
`277`	`282`	`{`
`278`	`283`	`return new NeverType();`