add array_first and array_last return type extensions (#4499)

canvural · web-flow · commit 46c25197d354 · 2025-10-31T13:19:41.000+01:00
diff --git a/src/Analyser/TypeSpecifier.php b/src/Analyser/TypeSpecifier.php
@@ -747,8 +747,8 @@ public function specifyTypesInCondition(
 					) {
 						$dimFetch = new ArrayDimFetch($arrayArg, $expr->var);
 						$iterableValueType = $expr->expr->name->toLowerString() === 'array_key_first'
-							? $arrayType->getFirstIterableValueType()
-							: $arrayType->getLastIterableValueType();
+							? $arrayType->getIterableValueType()
+							: $arrayType->getIterableValueType();
 
 						return $specifiedTypes->unionWith(
 							$this->create($dimFetch, $iterableValueType, TypeSpecifierContext::createTrue(), $scope),
@@ -775,7 +775,7 @@ public function specifyTypesInCondition(
 						$dimFetch = new ArrayDimFetch($arrayArg, $expr->var);
 
 						return $specifiedTypes->unionWith(
-							$this->create($dimFetch, $arrayType->getLastIterableValueType(), TypeSpecifierContext::createTrue(), $scope),
+							$this->create($dimFetch, $arrayType->getIterableValueType(), TypeSpecifierContext::createTrue(), $scope),
 						);
 					}
 				}
diff --git a/src/Type/IntersectionType.php b/src/Type/IntersectionType.php
@@ -690,12 +690,12 @@ public function getIterableKeyType(): Type
 
 	public function getFirstIterableKeyType(): Type
 	{
-		return $this->intersectTypes(static fn (Type $type): Type => $type->getFirstIterableKeyType());
+		return $this->intersectTypes(static fn (Type $type): Type => $type->getIterableKeyType());
 	}
 
 	public function getLastIterableKeyType(): Type
 	{
-		return $this->intersectTypes(static fn (Type $type): Type => $type->getLastIterableKeyType());
+		return $this->intersectTypes(static fn (Type $type): Type => $type->getIterableKeyType());
 	}
 
 	public function getIterableValueType(): Type
@@ -705,12 +705,12 @@ public function getIterableValueType(): Type
 
 	public function getFirstIterableValueType(): Type
 	{
-		return $this->intersectTypes(static fn (Type $type): Type => $type->getFirstIterableValueType());
+		return $this->intersectTypes(static fn (Type $type): Type => $type->getIterableValueType());
 	}
 
 	public function getLastIterableValueType(): Type
 	{
-		return $this->intersectTypes(static fn (Type $type): Type => $type->getLastIterableValueType());
+		return $this->intersectTypes(static fn (Type $type): Type => $type->getIterableValueType());
 	}
 
 	public function isArray(): TrinaryLogic
diff --git a/src/Type/Php/ArrayFirstLastDynamicReturnTypeExtension.php b/src/Type/Php/ArrayFirstLastDynamicReturnTypeExtension.php
@@ -0,0 +1,49 @@
+<?php declare(strict_types = 1);
+
+namespace PHPStan\Type\Php;
+
+use PhpParser\Node\Expr\FuncCall;
+use PHPStan\Analyser\Scope;
+use PHPStan\DependencyInjection\AutowiredService;
+use PHPStan\Reflection\FunctionReflection;
+use PHPStan\Type\DynamicFunctionReturnTypeExtension;
+use PHPStan\Type\NullType;
+use PHPStan\Type\Type;
+use PHPStan\Type\TypeCombinator;
+use function count;
+use function in_array;
+
+#[AutowiredService]
+final class ArrayFirstLastDynamicReturnTypeExtension implements DynamicFunctionReturnTypeExtension
+{
+
+	public function isFunctionSupported(FunctionReflection $functionReflection): bool
+	{
+		return in_array($functionReflection->getName(), ['array_first', 'array_last'], true);
+	}
+
+	public function getTypeFromFunctionCall(FunctionReflection $functionReflection, FuncCall $functionCall, Scope $scope): ?Type
+	{
+		$args = $functionCall->getArgs();
+
+		if (count($args) < 1) {
+			return null;
+		}
+
+		$argType = $scope->getType($args[0]->value);
+		$iterableAtLeastOnce = $argType->isIterableAtLeastOnce();
+
+		if ($iterableAtLeastOnce->no()) {
+			return new NullType();
+		}
+
+		$valueType = $argType->getIterableValueType();
+
+		if ($iterableAtLeastOnce->yes()) {
+			return $valueType;
+		}
+
+		return TypeCombinator::union($valueType, new NullType());
+	}
+
+}
diff --git a/src/Type/Php/ArrayKeyFirstDynamicReturnTypeExtension.php b/src/Type/Php/ArrayKeyFirstDynamicReturnTypeExtension.php
@@ -32,7 +32,7 @@ public function getTypeFromFunctionCall(FunctionReflection $functionReflection,
 			return new NullType();
 		}
 
-		$keyType = $argType->getFirstIterableKeyType();
+		$keyType = $argType->getIterableKeyType();
 		if ($iterableAtLeastOnce->yes()) {
 			return $keyType;
 		}
diff --git a/src/Type/Php/ArrayKeyLastDynamicReturnTypeExtension.php b/src/Type/Php/ArrayKeyLastDynamicReturnTypeExtension.php
@@ -32,7 +32,7 @@ public function getTypeFromFunctionCall(FunctionReflection $functionReflection,
 			return new NullType();
 		}
 
-		$keyType = $argType->getLastIterableKeyType();
+		$keyType = $argType->getIterableKeyType();
 		if ($iterableAtLeastOnce->yes()) {
 			return $keyType;
 		}
diff --git a/src/Type/Php/ArrayPointerFunctionsDynamicReturnTypeExtension.php b/src/Type/Php/ArrayPointerFunctionsDynamicReturnTypeExtension.php
@@ -45,8 +45,8 @@ public function getTypeFromFunctionCall(
 		}
 
 		$itemType = $functionReflection->getName() === 'reset'
-			? $argType->getFirstIterableValueType()
-			: $argType->getLastIterableValueType();
+			? $argType->getIterableValueType()
+			: $argType->getIterableValueType();
 		if ($iterableAtLeastOnce->yes()) {
 			return $itemType;
 		}
diff --git a/src/Type/Php/ArrayPopFunctionReturnTypeExtension.php b/src/Type/Php/ArrayPopFunctionReturnTypeExtension.php
@@ -32,7 +32,7 @@ public function getTypeFromFunctionCall(FunctionReflection $functionReflection,
 			return new NullType();
 		}
 
-		$itemType = $argType->getLastIterableValueType();
+		$itemType = $argType->getIterableValueType();
 		if ($iterableAtLeastOnce->yes()) {
 			return $itemType;
 		}
diff --git a/src/Type/Php/ArrayShiftFunctionReturnTypeExtension.php b/src/Type/Php/ArrayShiftFunctionReturnTypeExtension.php
@@ -32,7 +32,7 @@ public function getTypeFromFunctionCall(FunctionReflection $functionReflection,
 			return new NullType();
 		}
 
-		$itemType = $argType->getFirstIterableValueType();
+		$itemType = $argType->getIterableValueType();
 		if ($iterableAtLeastOnce->yes()) {
 			return $itemType;
 		}
diff --git a/src/Type/StaticType.php b/src/Type/StaticType.php
@@ -401,12 +401,12 @@ public function getIterableKeyType(): Type
 
 	public function getFirstIterableKeyType(): Type
 	{
-		return $this->getStaticObjectType()->getFirstIterableKeyType();
+		return $this->getStaticObjectType()->getIterableKeyType();
 	}
 
 	public function getLastIterableKeyType(): Type
 	{
-		return $this->getStaticObjectType()->getLastIterableKeyType();
+		return $this->getStaticObjectType()->getIterableKeyType();
 	}
 
 	public function getIterableValueType(): Type
@@ -416,12 +416,12 @@ public function getIterableValueType(): Type
 
 	public function getFirstIterableValueType(): Type
 	{
-		return $this->getStaticObjectType()->getFirstIterableValueType();
+		return $this->getStaticObjectType()->getIterableValueType();
 	}
 
 	public function getLastIterableValueType(): Type
 	{
-		return $this->getStaticObjectType()->getLastIterableValueType();
+		return $this->getStaticObjectType()->getIterableValueType();
 	}
 
 	public function isOffsetAccessible(): TrinaryLogic
diff --git a/src/Type/Traits/LateResolvableTypeTrait.php b/src/Type/Traits/LateResolvableTypeTrait.php
@@ -200,12 +200,12 @@ public function getIterableKeyType(): Type
 
 	public function getFirstIterableKeyType(): Type
 	{
-		return $this->resolve()->getFirstIterableKeyType();
+		return $this->resolve()->getIterableKeyType();
 	}
 
 	public function getLastIterableKeyType(): Type
 	{
-		return $this->resolve()->getLastIterableKeyType();
+		return $this->resolve()->getIterableKeyType();
 	}
 
 	public function getIterableValueType(): Type
@@ -215,12 +215,12 @@ public function getIterableValueType(): Type
 
 	public function getFirstIterableValueType(): Type
 	{
-		return $this->resolve()->getFirstIterableValueType();
+		return $this->resolve()->getIterableValueType();
 	}
 
 	public function getLastIterableValueType(): Type
 	{
-		return $this->resolve()->getLastIterableValueType();
+		return $this->resolve()->getIterableValueType();
 	}
 
 	public function isArray(): TrinaryLogic
diff --git a/src/Type/Type.php b/src/Type/Type.php
@@ -117,14 +117,18 @@ public function getArraySize(): Type;
 
 	public function getIterableKeyType(): Type;
 
+	/** @deprecated use getIterableKeyType */
 	public function getFirstIterableKeyType(): Type;
 
+	/** @deprecated use getIterableKeyType */
 	public function getLastIterableKeyType(): Type;
 
 	public function getIterableValueType(): Type;
 
+	/** @deprecated use getIterableValueType */
 	public function getFirstIterableValueType(): Type;
 
+	/** @deprecated use getIterableValueType */
 	public function getLastIterableValueType(): Type;
 
 	public function isArray(): TrinaryLogic;
diff --git a/src/Type/TypeCombinator.php b/src/Type/TypeCombinator.php
@@ -933,7 +933,7 @@ private static function optimizeConstantArrays(array $types): array
 			$valueTypes = [];
 			foreach ($results as $result) {
 				$keyTypes[] = $result->getIterableKeyType();
-				$valueTypes[] = $result->getLastIterableValueType();
+				$valueTypes[] = $result->getIterableValueType();
 				if ($result->isList()->yes()) {
 					continue;
 				}
diff --git a/src/Type/UnionType.php b/src/Type/UnionType.php
@@ -639,12 +639,12 @@ public function getIterableKeyType(): Type
 
 	public function getFirstIterableKeyType(): Type
 	{
-		return $this->unionTypes(static fn (Type $type): Type => $type->getFirstIterableKeyType());
+		return $this->unionTypes(static fn (Type $type): Type => $type->getIterableKeyType());
 	}
 
 	public function getLastIterableKeyType(): Type
 	{
-		return $this->unionTypes(static fn (Type $type): Type => $type->getLastIterableKeyType());
+		return $this->unionTypes(static fn (Type $type): Type => $type->getIterableKeyType());
 	}
 
 	public function getIterableValueType(): Type
@@ -654,12 +654,12 @@ public function getIterableValueType(): Type
 
 	public function getFirstIterableValueType(): Type
 	{
-		return $this->unionTypes(static fn (Type $type): Type => $type->getFirstIterableValueType());
+		return $this->unionTypes(static fn (Type $type): Type => $type->getIterableValueType());
 	}
 
 	public function getLastIterableValueType(): Type
 	{
-		return $this->unionTypes(static fn (Type $type): Type => $type->getLastIterableValueType());
+		return $this->unionTypes(static fn (Type $type): Type => $type->getIterableValueType());
 	}
 
 	public function isArray(): TrinaryLogic
diff --git a/tests/PHPStan/Analyser/LegacyNodeScopeResolverTest.php b/tests/PHPStan/Analyser/LegacyNodeScopeResolverTest.php
@@ -4790,7 +4790,7 @@ public static function dataArrayFunctions(): array
 				'array_map(function (): \stdClass {}, $conditionalKeysArray)',
 			],
 			[
-				'stdClass',
+				'\'foo\'|stdClass',
 				'array_pop($stringKeys)',
 			],
 			[
@@ -4802,7 +4802,7 @@ public static function dataArrayFunctions(): array
 				'array_pop($stdClassesWithIsset)',
 			],
 			[
-				'\'foo\'',
+				'\'foo\'|stdClass',
 				'array_shift($stringKeys)',
 			],
 			[
@@ -7169,23 +7169,23 @@ public static function dataArrayPointerFunctions(): array
 				'reset($emptyConstantArray)',
 			],
 			[
-				'1',
+				'1|2',
 				'reset($constantArray)',
 			],
 			[
-				'\'baz\'|\'foo\'',
+				'\'bar\'|\'baz\'|\'foo\'',
 				'reset($conditionalArray)',
 			],
 			[
-				'0|1',
+				'0|1|2',
 				'reset($constantArrayOptionalKeys1)',
 			],
 			[
-				'0',
+				'0|1|2',
 				'reset($constantArrayOptionalKeys2)',
 			],
 			[
-				'0',
+				'0|1|2',
 				'reset($constantArrayOptionalKeys3)',
 			],
 			[
@@ -7205,23 +7205,23 @@ public static function dataArrayPointerFunctions(): array
 				'end($emptyConstantArray)',
 			],
 			[
-				'2',
+				'1|2',
 				'end($constantArray)',
 			],
 			[
-				'\'bar\'|\'baz\'',
+				'\'bar\'|\'baz\'|\'foo\'',
 				'end($secondConditionalArray)',
 			],
 			[
-				'2',
+				'0|1|2',
 				'end($constantArrayOptionalKeys1)',
 			],
 			[
-				'2',
+				'0|1|2',
 				'end($constantArrayOptionalKeys2)',
 			],
 			[
-				'1|2',
+				'0|1|2',
 				'end($constantArrayOptionalKeys3)',
 			],
 		];
@@ -8644,43 +8644,43 @@ public static function dataPhp73Functions(): array
 				'array_key_last($emptyArray)',
 			],
 			[
-				'0',
+				'0|1|2',
 				'array_key_first($literalArray)',
 			],
 			[
-				'2',
+				'0|1|2',
 				'array_key_last($literalArray)',
 			],
 			[
-				'0',
+				'0|1|2|3',
 				'array_key_first($anotherLiteralArray)',
 			],
 			[
-				'2|3',
+				'0|1|2|3',
 				'array_key_last($anotherLiteralArray)',
 			],
 			[
-				"'a'|'b'",
+				"'a'|'b'|'c'",
 				'array_key_first($constantArrayOptionalKeys1)',
 			],
 			[
-				"'c'",
+				"'a'|'b'|'c'",
 				'array_key_last($constantArrayOptionalKeys1)',
 			],
 			[
-				"'a'",
+				"'a'|'b'|'c'",
 				'array_key_first($constantArrayOptionalKeys2)',
 			],
 			[
-				"'c'",
+				"'a'|'b'|'c'",
 				'array_key_last($constantArrayOptionalKeys2)',
 			],
 			[
-				"'a'",
+				"'a'|'b'|'c'",
 				'array_key_first($constantArrayOptionalKeys3)',
 			],
 			[
-				"'b'|'c'",
+				"'a'|'b'|'c'",
 				'array_key_last($constantArrayOptionalKeys3)',
 			],
 			[
diff --git a/tests/PHPStan/Analyser/nsrt/array-pop.php b/tests/PHPStan/Analyser/nsrt/array-pop.php
diff --git a/tests/PHPStan/Analyser/nsrt/array-shift.php b/tests/PHPStan/Analyser/nsrt/array-shift.php
diff --git a/tests/PHPStan/Analyser/nsrt/array_first_last.php b/tests/PHPStan/Analyser/nsrt/array_first_last.php
diff --git a/tests/PHPStan/Analyser/nsrt/bug-8084.php b/tests/PHPStan/Analyser/nsrt/bug-8084.php
diff --git a/tests/PHPStan/Rules/Arrays/NonexistentOffsetInArrayDimFetchRuleTest.php b/tests/PHPStan/Rules/Arrays/NonexistentOffsetInArrayDimFetchRuleTest.php

Original file line number	Diff line number	Diff line change
`@@ -690,12 +690,12 @@ public function getIterableKeyType(): Type`
`690`	`690`
`691`	`691`	`public function getFirstIterableKeyType(): Type`
`692`	`692`	`{`
`693`		`- return $this->intersectTypes(static fn (Type $type): Type => $type->getFirstIterableKeyType());`
	`693`	`+ return $this->intersectTypes(static fn (Type $type): Type => $type->getIterableKeyType());`
`694`	`694`	`}`
`695`	`695`
`696`	`696`	`public function getLastIterableKeyType(): Type`
`697`	`697`	`{`
`698`		`- return $this->intersectTypes(static fn (Type $type): Type => $type->getLastIterableKeyType());`
	`698`	`+ return $this->intersectTypes(static fn (Type $type): Type => $type->getIterableKeyType());`
`699`	`699`	`}`
`700`	`700`
`701`	`701`	`public function getIterableValueType(): Type`
`@@ -705,12 +705,12 @@ public function getIterableValueType(): Type`
`705`	`705`
`706`	`706`	`public function getFirstIterableValueType(): Type`
`707`	`707`	`{`
`708`		`- return $this->intersectTypes(static fn (Type $type): Type => $type->getFirstIterableValueType());`
	`708`	`+ return $this->intersectTypes(static fn (Type $type): Type => $type->getIterableValueType());`
`709`	`709`	`}`
`710`	`710`
`711`	`711`	`public function getLastIterableValueType(): Type`
`712`	`712`	`{`
`713`		`- return $this->intersectTypes(static fn (Type $type): Type => $type->getLastIterableValueType());`
	`713`	`+ return $this->intersectTypes(static fn (Type $type): Type => $type->getIterableValueType());`
`714`	`714`	`}`
`715`	`715`
`716`	`716`	`public function isArray(): TrinaryLogic`
Original file line number	Diff line number	Diff line change
`@@ -32,7 +32,7 @@ public function getTypeFromFunctionCall(FunctionReflection $functionReflection,`
`32`	`32`	`return new NullType();`
`33`	`33`	`}`
`34`	`34`
`35`		`- $keyType = $argType->getFirstIterableKeyType();`
	`35`	`+ $keyType = $argType->getIterableKeyType();`
`36`	`36`	`if ($iterableAtLeastOnce->yes()) {`
`37`	`37`	`return $keyType;`
`38`	`38`	`}`
Original file line number	Diff line number	Diff line change
`@@ -45,8 +45,8 @@ public function getTypeFromFunctionCall(`
`45`	`45`	`}`
`46`	`46`
`47`	`47`	`$itemType = $functionReflection->getName() === 'reset'`
`48`		`- ? $argType->getFirstIterableValueType()`
`49`		`- : $argType->getLastIterableValueType();`
	`48`	`+ ? $argType->getIterableValueType()`
	`49`	`+ : $argType->getIterableValueType();`
`50`	`50`	`if ($iterableAtLeastOnce->yes()) {`
`51`	`51`	`return $itemType;`
`52`	`52`	`}`
Original file line number	Diff line number	Diff line change
`@@ -401,12 +401,12 @@ public function getIterableKeyType(): Type`
`401`	`401`
`402`	`402`	`public function getFirstIterableKeyType(): Type`
`403`	`403`	`{`
`404`		`- return $this->getStaticObjectType()->getFirstIterableKeyType();`
	`404`	`+ return $this->getStaticObjectType()->getIterableKeyType();`
`405`	`405`	`}`
`406`	`406`
`407`	`407`	`public function getLastIterableKeyType(): Type`
`408`	`408`	`{`
`409`		`- return $this->getStaticObjectType()->getLastIterableKeyType();`
	`409`	`+ return $this->getStaticObjectType()->getIterableKeyType();`
`410`	`410`	`}`
`411`	`411`
`412`	`412`	`public function getIterableValueType(): Type`
`@@ -416,12 +416,12 @@ public function getIterableValueType(): Type`
`416`	`416`
`417`	`417`	`public function getFirstIterableValueType(): Type`
`418`	`418`	`{`
`419`		`- return $this->getStaticObjectType()->getFirstIterableValueType();`
	`419`	`+ return $this->getStaticObjectType()->getIterableValueType();`
`420`	`420`	`}`
`421`	`421`
`422`	`422`	`public function getLastIterableValueType(): Type`
`423`	`423`	`{`
`424`		`- return $this->getStaticObjectType()->getLastIterableValueType();`
	`424`	`+ return $this->getStaticObjectType()->getIterableValueType();`
`425`	`425`	`}`
`426`	`426`
`427`	`427`	`public function isOffsetAccessible(): TrinaryLogic`
Original file line number	Diff line number	Diff line change
`@@ -200,12 +200,12 @@ public function getIterableKeyType(): Type`
`200`	`200`
`201`	`201`	`public function getFirstIterableKeyType(): Type`
`202`	`202`	`{`
`203`		`- return $this->resolve()->getFirstIterableKeyType();`
	`203`	`+ return $this->resolve()->getIterableKeyType();`
`204`	`204`	`}`
`205`	`205`
`206`	`206`	`public function getLastIterableKeyType(): Type`
`207`	`207`	`{`
`208`		`- return $this->resolve()->getLastIterableKeyType();`
	`208`	`+ return $this->resolve()->getIterableKeyType();`
`209`	`209`	`}`
`210`	`210`
`211`	`211`	`public function getIterableValueType(): Type`
`@@ -215,12 +215,12 @@ public function getIterableValueType(): Type`
`215`	`215`
`216`	`216`	`public function getFirstIterableValueType(): Type`
`217`	`217`	`{`
`218`		`- return $this->resolve()->getFirstIterableValueType();`
	`218`	`+ return $this->resolve()->getIterableValueType();`
`219`	`219`	`}`
`220`	`220`
`221`	`221`	`public function getLastIterableValueType(): Type`
`222`	`222`	`{`
`223`		`- return $this->resolve()->getLastIterableValueType();`
	`223`	`+ return $this->resolve()->getIterableValueType();`
`224`	`224`	`}`
`225`	`225`
`226`	`226`	`public function isArray(): TrinaryLogic`