Improve precision of filter_var/filter_input return types for typed array inputs

When the input array has a known value type (e.g. array<int>, array<array<int>>),
use that type information instead of always adding generic array to the value type.

- When value type is definitely not array (e.g. array<int>): don't add array
- When value type is definitely array (e.g. array<array<int>>): recursively
  compute the precise nested filtered type
- When value type is a union of scalar and array (e.g. array<int|array<int>>):
  extract scalar/array parts and handle each precisely
- For mixed/unknown value types: fall back to array<mixed, mixed> as before

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: phpstan-bot

src/Type/Php/FilterFunctionReturnTypeHelper.php

@@ -165,9 +165,21 @@ public function getType(Type $inputType, ?Type $filterType, ?Type $flagsType): T
 			return $mixedType;
 		}
 
+		$inputValueType = null;
 		if ($inputIsArray->yes() && ($hasRequireArrayFlag->yes() || $hasForceArrayFlag->yes())) {
 			$inputArrayKeyType = $inputType->getIterableKeyType();
 			$inputType = $inputType->getIterableValueType();
+			$inputValueType = $inputType;
+
+			// When the value type is a union of scalar and array types (e.g. int|array<int>),
+			// only use the scalar part for scalar filtering - array parts are handled separately
+			// via recursive filtering in addNestedArrayType
+			if ($inputType->isArray()->maybe()) {
+				$scalarPart = TypeCombinator::remove($inputType, new ArrayType($mixedType, $mixedType));
+				if (!$scalarPart instanceof NeverType) {
+					$inputType = $scalarPart;
+				}
+			}
 		}
 
 		if ($inputType->isScalar()->no() && $inputType->isNull()->no()) {
@@ -198,19 +210,15 @@ public function getType(Type $inputType, ?Type $filterType, ?Type $flagsType): T
 		}
 
 		if ($hasRequireArrayFlag->yes()) {
-			if (!$inputIsArray->no()) {
-				$type = TypeCombinator::union($type, new ArrayType($mixedType, $mixedType));
-			}
+			$type = $this->addNestedArrayType($type, $inputValueType, $inputIsArray, $filterType, $flagsType, $mixedType);
 			$type = new ArrayType($inputArrayKeyType ?? $mixedType, $type);
 			if (!$inputIsArray->yes()) {
 				$type = TypeCombinator::union($type, $defaultType);
 			}
 		}
 
 		if ($hasRequireArrayFlag->no() && $hasForceArrayFlag->yes()) {
-			if (!$inputIsArray->no()) {
-				$type = TypeCombinator::union($type, new ArrayType($mixedType, $mixedType));
-			}
+			$type = $this->addNestedArrayType($type, $inputValueType, $inputIsArray, $filterType, $flagsType, $mixedType);
 			return new ArrayType($inputArrayKeyType ?? $mixedType, $type);
 		}
 
@@ -221,6 +229,40 @@ public function getType(Type $inputType, ?Type $filterType, ?Type $flagsType): T
 		return $type;
 	}
 
+	private function addNestedArrayType(Type $type, ?Type $inputValueType, TrinaryLogic $inputIsArray, ?Type $filterType, ?Type $flagsType, MixedType $mixedType): Type
+	{
+		if ($inputValueType !== null) {
+			// Input was unwrapped - check if the value type could be an array
+			$valueTypeIsArray = $inputValueType->isArray();
+			if ($valueTypeIsArray->yes()) {
+				// Value type is definitely an array - recursively compute precise nested type
+				// Replace $type entirely since the scalar filtering path produces incorrect
+				// results for array inputs (arrays are recursively filtered, not failed)
+				return $this->getType($inputValueType, $filterType, $flagsType);
+			}
+			if ($valueTypeIsArray->maybe()) {
+				// Value type is a union of scalar and array types (e.g. int|array<int>)
+				// Try to extract the array part for precise recursive filtering
+				$inputArrayPart = TypeCombinator::intersect($inputValueType, new ArrayType($mixedType, $mixedType));
+				if (!$inputArrayPart instanceof NeverType && !$inputArrayPart->getIterableValueType() instanceof MixedType) {
+					$nestedType = $this->getType($inputArrayPart, $filterType, $flagsType);
+					return TypeCombinator::union($type, $nestedType);
+				}
+				// Fall back to generic array for mixed-like value types
+				return TypeCombinator::union($type, new ArrayType($mixedType, $mixedType));
+			}
+			// Value type is definitely not an array - don't add array to type
+			return $type;
+		}
+
+		// No unwrap happened (input is maybe-array, e.g. from filter_input with mixed)
+		if (!$inputIsArray->no()) {
+			return TypeCombinator::union($type, new ArrayType($mixedType, $mixedType));
+		}
+
+		return $type;
+	}
+
 	/**
 	 * @return array<int, Type>
 	 */

tests/PHPStan/Analyser/nsrt/bug-11339.php

@@ -24,3 +24,39 @@
 
 $k = filter_var('foo', FILTER_VALIDATE_INT, FILTER_FORCE_ARRAY);
 assertType('array<false>', $k);
+
+/**
+ * @param array<int> $arrayOfInt
+ * @param array<array<int>> $arrayOfArrayOfInt
+ * @param array<int|array<int>> $arrayOfIntOrArrayOfInt
+ */
+function typedArrayInputs(array $arrayOfInt, array $arrayOfArrayOfInt, array $arrayOfIntOrArrayOfInt): void
+{
+	// array<int> - values are ints, not arrays, so no array in value type
+	$l = filter_var($arrayOfInt, FILTER_VALIDATE_INT, ['flags' => FILTER_REQUIRE_ARRAY]);
+	assertType('array<int>', $l);
+
+	$m = filter_var($arrayOfInt, FILTER_VALIDATE_INT, ['flags' => FILTER_REQUIRE_ARRAY|FILTER_NULL_ON_FAILURE]);
+	assertType('array<int>', $m);
+
+	// array<array<int>> - values are arrays, recursively filtered
+	$n = filter_var($arrayOfArrayOfInt, FILTER_VALIDATE_INT, ['flags' => FILTER_REQUIRE_ARRAY]);
+	assertType('array<array<int>>', $n);
+
+	$o = filter_var($arrayOfArrayOfInt, FILTER_VALIDATE_INT, ['flags' => FILTER_REQUIRE_ARRAY|FILTER_NULL_ON_FAILURE]);
+	assertType('array<array<int>>', $o);
+
+	// array<int|array<int>> - mixed values, both scalar and array possible
+	$p = filter_var($arrayOfIntOrArrayOfInt, FILTER_VALIDATE_INT, ['flags' => FILTER_REQUIRE_ARRAY]);
+	assertType('array<array<int>|int>', $p);
+
+	$q = filter_var($arrayOfIntOrArrayOfInt, FILTER_VALIDATE_INT, ['flags' => FILTER_REQUIRE_ARRAY|FILTER_NULL_ON_FAILURE]);
+	assertType('array<array<int>|int>', $q);
+
+	// FORCE_ARRAY with typed arrays
+	$r = filter_var($arrayOfInt, FILTER_VALIDATE_INT, ['flags' => FILTER_FORCE_ARRAY]);
+	assertType('array<int>', $r);
+
+	$s = filter_var($arrayOfArrayOfInt, FILTER_VALIDATE_INT, ['flags' => FILTER_FORCE_ARRAY]);
+	assertType('array<array<int>>', $s);
+}