Add Type::spliceArray(), improve splice_array() array type narrowing

phpstan-baseline.neon

@@ -969,7 +969,7 @@ parameters:
 		-
 			message: '#^Doing instanceof PHPStan\\Type\\Constant\\ConstantArrayType is error\-prone and deprecated\. Use Type\:\:getConstantArrays\(\) instead\.$#'
 			identifier: phpstanApi.instanceofType
-			count: 5
+			count: 6
 			path: src/Type/Constant/ConstantArrayType.php
 
 		-

src/Analyser/NodeScopeResolver.php

@@ -2670,19 +2670,20 @@ static function (): void {
 			if (
 				$functionReflection !== null
 				&& $functionReflection->getName() === 'array_splice'
-				&& count($expr->getArgs()) >= 1
+				&& count($expr->getArgs()) >= 2
 			) {
 				$arrayArg = $expr->getArgs()[0]->value;
 				$arrayArgType = $scope->getType($arrayArg);
-				$valueType = $arrayArgType->getIterableValueType();
-				if (count($expr->getArgs()) >= 4) {
-					$replacementType = $scope->getType($expr->getArgs()[3]->value)->toArray();
-					$valueType = TypeCombinator::union($valueType, $replacementType->getIterableValueType());
-				}
+				$arrayArgNativeType = $scope->getNativeType($arrayArg);
+
+				$offsetType = $scope->getType($expr->getArgs()[1]->value);
+				$lengthType = isset($expr->getArgs()[2]) ? $scope->getType($expr->getArgs()[2]->value) : new NullType();
+				$replacementType = isset($expr->getArgs()[3]) ? $scope->getType($expr->getArgs()[3]->value) : new ConstantArrayType([], []);
+
 				$scope = $scope->invalidateExpression($arrayArg)->assignExpression(
 					$arrayArg,
-					new ArrayType($arrayArgType->getIterableKeyType(), $valueType),
-					new ArrayType($arrayArgType->getIterableKeyType(), $valueType),
+					$arrayArgType->spliceArray($offsetType, $lengthType, $replacementType),
+					$arrayArgNativeType->spliceArray($offsetType, $lengthType, $replacementType),
 				);
 			}
 

src/Type/Accessory/AccessoryArrayListType.php

@@ -248,6 +248,11 @@ public function sliceArray(Type $offsetType, Type $lengthType, TrinaryLogic $pre
 		return new MixedType();
 	}
 
+	public function spliceArray(Type $offsetType, Type $lengthType, Type $replacementType): Type
+	{
+		return $this;
+	}
+
 	public function isIterable(): TrinaryLogic
 	{
 		return TrinaryLogic::createYes();

src/Type/Accessory/HasOffsetType.php

@@ -214,6 +214,15 @@ public function sliceArray(Type $offsetType, Type $lengthType, TrinaryLogic $pre
 		return new MixedType();
 	}
 
+	public function spliceArray(Type $offsetType, Type $lengthType, Type $replacementType): Type
+	{
+		if ((new ConstantIntegerType(0))->isSuperTypeOf($lengthType)->yes()) {
+			return $this;
+		}
+
+		return new MixedType();
+	}
+
 	public function isIterableAtLeastOnce(): TrinaryLogic
 	{
 		return TrinaryLogic::createYes();

src/Type/Accessory/HasOffsetValueType.php

@@ -274,6 +274,15 @@ public function sliceArray(Type $offsetType, Type $lengthType, TrinaryLogic $pre
 		return new MixedType();
 	}
 
+	public function spliceArray(Type $offsetType, Type $lengthType, Type $replacementType): Type
+	{
+		if ((new ConstantIntegerType(0))->isSuperTypeOf($lengthType)->yes()) {
+			return $this;
+		}
+
+		return new MixedType();
+	}
+
 	public function isIterableAtLeastOnce(): TrinaryLogic
 	{
 		return TrinaryLogic::createYes();

src/Type/Accessory/NonEmptyArrayType.php

@@ -223,6 +223,18 @@ public function sliceArray(Type $offsetType, Type $lengthType, TrinaryLogic $pre
 		return new MixedType();
 	}
 
+	public function spliceArray(Type $offsetType, Type $lengthType, Type $replacementType): Type
+	{
+		if (
+			(new ConstantIntegerType(0))->isSuperTypeOf($lengthType)->yes()
+			|| $replacementType->toArray()->isIterableAtLeastOnce()->yes()
+		) {
+			return $this;
+		}
+
+		return new MixedType();
+	}
+
 	public function isIterable(): TrinaryLogic
 	{
 		return TrinaryLogic::createYes();

src/Type/Accessory/OversizedArrayType.php

@@ -214,6 +214,11 @@ public function sliceArray(Type $offsetType, Type $lengthType, TrinaryLogic $pre
 		return $this;
 	}
 
+	public function spliceArray(Type $offsetType, Type $lengthType, Type $replacementType): Type
+	{
+		return $this;
+	}
+
 	public function isIterable(): TrinaryLogic
 	{
 		return TrinaryLogic::createYes();

src/Type/ArrayType.php

@@ -453,6 +453,27 @@ public function sliceArray(Type $offsetType, Type $lengthType, TrinaryLogic $pre
 		return $this;
 	}
 
+	public function spliceArray(Type $offsetType, Type $lengthType, Type $replacementType): Type
+	{
+		$replacementArrayType = $replacementType->toArray();
+		$replacementArrayTypeIsIterableAtLeastOnce = $replacementArrayType->isIterableAtLeastOnce();
+
+		if ((new ConstantIntegerType(0))->isSuperTypeOf($offsetType)->yes() && $lengthType->isNull()->yes() && $replacementArrayTypeIsIterableAtLeastOnce->no()) {
+			return new ConstantArrayType([], []);
+		}
+
+		$arrayType = new self(
+			TypeCombinator::union($this->getIterableKeyType(), $replacementArrayType->getKeysArray()->getIterableKeyType()),
+			TypeCombinator::union($this->getIterableValueType(), $replacementArrayType->getIterableValueType()),
+		);
+
+		if ($replacementArrayTypeIsIterableAtLeastOnce->yes()) {
+			$arrayType = TypeCombinator::intersect($arrayType, new NonEmptyArrayType());
+		}
+
+		return $arrayType;
+	}
+
 	public function isCallable(): TrinaryLogic
 	{
 		return TrinaryLogic::createMaybe()->and($this->itemType->isString());

src/Type/Constant/ConstantArrayType.php

@@ -913,10 +913,7 @@ public function shiftArray(): Type
 
 	public function shuffleArray(): Type
 	{
-		$builder = ConstantArrayTypeBuilder::createFromConstantArray($this->getValuesArray());
-		$builder->degradeToGeneralArray();
-
-		return $builder->getArray();
+		return $this->getValuesArray()->degradeToGeneralArray();
 	}
 
 	public function sliceArray(Type $offsetType, Type $lengthType, TrinaryLogic $preserveKeys): Type
@@ -937,10 +934,7 @@ public function sliceArray(Type $offsetType, Type $lengthType, TrinaryLogic $pre
 		}
 
 		if ($offset === null || $length === null) {
-			$builder = ConstantArrayTypeBuilder::createFromConstantArray($this);
-			$builder->degradeToGeneralArray();
-
-			return $builder->getArray()
+			return $this->degradeToGeneralArray()
 				->sliceArray($offsetType, $lengthType, $preserveKeys);
 		}
 
@@ -1022,6 +1016,108 @@ public function sliceArray(Type $offsetType, Type $lengthType, TrinaryLogic $pre
 		return $builder->getArray();
 	}
 
+	public function spliceArray(Type $offsetType, Type $lengthType, Type $replacementType): Type
+	{
+		$keyTypesCount = count($this->keyTypes);
+
+		$offset = $offsetType instanceof ConstantIntegerType ? $offsetType->getValue() : null;
+
+		if ($lengthType instanceof ConstantIntegerType) {
+			$length = $lengthType->getValue();
+		} elseif ($lengthType->isNull()->yes()) {
+			$length = $keyTypesCount;
+		} else {
+			$length = null;
+		}
+
+		if ($offset === null || $length === null) {
+			return $this->degradeToGeneralArray()
+				->spliceArray($offsetType, $lengthType, $replacementType);
+		}
+
+		if ($keyTypesCount + $offset <= 0) {
+			// A negative offset cannot reach left outside the array twice
+			$offset = 0;
+		}
+
+		if ($keyTypesCount + $length <= 0) {
+			// A negative length cannot reach left outside the array twice
+			$length = 0;
+		}
+
+		$offsetWasNegative = false;
+		if ($offset < 0) {
+			$offsetWasNegative = true;
+			$offset = $keyTypesCount + $offset;
+		}
+
+		if ($length < 0) {
+			$length = $keyTypesCount - $offset + $length;
+		}
+
+		$extractType = $this->sliceArray($offsetType, $lengthType, TrinaryLogic::createYes());
+
+		$types = [];
+		foreach ($replacementType->toArray()->getArrays() as $replacementArrayType) {
+			$removeKeysCount = 0;
+			$optionalKeysBeforeReplacement = 0;
+
+			$builder = ConstantArrayTypeBuilder::createEmpty();
+			for ($i = 0;; $i++) {
+				$isOptional = $this->isOptionalKey($i);
+
+				if (!$offsetWasNegative && $i < $offset && $isOptional) {
+					$optionalKeysBeforeReplacement++;
+				}
+
+				if ($i === $offset + $optionalKeysBeforeReplacement) {
+					// When the offset is reached we have to a) put the replacement array in and b) remove $length elements
+					$removeKeysCount = $length;
+
+					if ($replacementArrayType instanceof self) {
+						$valuesArray = $replacementArrayType->getValuesArray();
+						for ($j = 0, $jMax = count($valuesArray->keyTypes); $j < $jMax; $j++) {
+							$builder->setOffsetValueType(null, $valuesArray->valueTypes[$j], $valuesArray->isOptionalKey($j));
+						}
+					} else {
+						$builder->degradeToGeneralArray();
+						$builder->setOffsetValueType($replacementArrayType->getValuesArray()->getIterableKeyType(), $replacementArrayType->getIterableValueType(), true);
+					}
+				}
+
+				if (!isset($this->keyTypes[$i])) {
+					break;
+				}
+
+				if ($removeKeysCount > 0) {
+					$extractTypeHasOffsetValueType = $extractType->hasOffsetValueType($this->keyTypes[$i]);
+
+					if (
+						(!$isOptional && $extractTypeHasOffsetValueType->yes())
+						|| ($isOptional && $extractTypeHasOffsetValueType->maybe())
+					) {
+						$removeKeysCount--;
+						continue;
+					}
+				}
+
+				if (!$isOptional && $extractType->hasOffsetValueType($this->keyTypes[$i])->maybe()) {
+					$isOptional = true;
+				}
+
+				$builder->setOffsetValueType(
+					$this->keyTypes[$i]->isInteger()->no() ? $this->keyTypes[$i] : null,
+					$this->valueTypes[$i],
+					$isOptional,
+				);
+			}
+
+			$types[] = $builder->getArray();
+		}
+
+		return TypeCombinator::union(...$types);
+	}
+
 	public function isIterableAtLeastOnce(): TrinaryLogic
 	{
 		$keysCount = count($this->keyTypes);
@@ -1262,6 +1358,14 @@ public function generalizeValues(): self
 		return new self($this->keyTypes, $valueTypes, $this->nextAutoIndexes, $this->optionalKeys, $this->isList);
 	}
 
+	private function degradeToGeneralArray(): Type
+	{
+		$builder = ConstantArrayTypeBuilder::createFromConstantArray($this);
+		$builder->degradeToGeneralArray();
+
+		return $builder->getArray();
+	}
+
 	public function getKeysArray(): self
 	{
 		return $this->getKeysOrValuesArray($this->keyTypes);

src/Type/IntersectionType.php

@@ -910,6 +910,11 @@ public function sliceArray(Type $offsetType, Type $lengthType, TrinaryLogic $pre
 		return $result;
 	}
 
+	public function spliceArray(Type $offsetType, Type $lengthType, Type $replacementType): Type
+	{
+		return $this->intersectTypes(static fn (Type $type): Type => $type->spliceArray($offsetType, $lengthType, $replacementType));
+	}
+
 	public function getEnumCases(): array
 	{
 		$compare = [];

src/Type/MixedType.php

@@ -287,6 +287,15 @@ public function sliceArray(Type $offsetType, Type $lengthType, TrinaryLogic $pre
 		return new ArrayType(new MixedType($this->isExplicitMixed), new MixedType($this->isExplicitMixed));
 	}
 
+	public function spliceArray(Type $offsetType, Type $lengthType, Type $replacementType): Type
+	{
+		if ($this->isArray()->no()) {
+			return new ErrorType();
+		}
+
+		return new ArrayType(new MixedType($this->isExplicitMixed), new MixedType($this->isExplicitMixed));
+	}
+
 	public function isCallable(): TrinaryLogic
 	{
 		if ($this->subtractedType !== null) {

src/Type/NeverType.php

@@ -333,6 +333,11 @@ public function sliceArray(Type $offsetType, Type $lengthType, TrinaryLogic $pre
 		return new NeverType();
 	}
 
+	public function spliceArray(Type $offsetType, Type $lengthType, Type $replacementType): Type
+	{
+		return new NeverType();
+	}
+
 	public function isCallable(): TrinaryLogic
 	{
 		return TrinaryLogic::createNo();

src/Type/StaticType.php

@@ -456,6 +456,11 @@ public function sliceArray(Type $offsetType, Type $lengthType, TrinaryLogic $pre
 		return $this->getStaticObjectType()->sliceArray($offsetType, $lengthType, $preserveKeys);
 	}
 
+	public function spliceArray(Type $offsetType, Type $lengthType, Type $replacementType): Type
+	{
+		return $this->getStaticObjectType()->spliceArray($offsetType, $lengthType, $replacementType);
+	}
+
 	public function isCallable(): TrinaryLogic
 	{
 		return $this->getStaticObjectType()->isCallable();

src/Type/Traits/LateResolvableTypeTrait.php

@@ -308,6 +308,11 @@ public function sliceArray(Type $offsetType, Type $lengthType, TrinaryLogic $pre
 		return $this->resolve()->sliceArray($offsetType, $lengthType, $preserveKeys);
 	}
 
+	public function spliceArray(Type $offsetType, Type $lengthType, Type $replacementType): Type
+	{
+		return $this->resolve()->spliceArray($offsetType, $lengthType, $replacementType);
+	}
+
 	public function isCallable(): TrinaryLogic
 	{
 		return $this->resolve()->isCallable();

src/Type/Traits/MaybeArrayTypeTrait.php

@@ -99,4 +99,9 @@ public function sliceArray(Type $offsetType, Type $lengthType, TrinaryLogic $pre
 		return new ErrorType();
 	}
 
+	public function spliceArray(Type $offsetType, Type $lengthType, Type $replacementType): Type
+	{
+		return new ErrorType();
+	}
+
 }

src/Type/Traits/NonArrayTypeTrait.php

@@ -99,4 +99,9 @@ public function sliceArray(Type $offsetType, Type $lengthType, TrinaryLogic $pre
 		return new ErrorType();
 	}
 
+	public function spliceArray(Type $offsetType, Type $lengthType, Type $replacementType): Type
+	{
+		return new ErrorType();
+	}
+
 }

src/Type/Type.php

@@ -158,6 +158,8 @@ public function shuffleArray(): Type;
 
 	public function sliceArray(Type $offsetType, Type $lengthType, TrinaryLogic $preserveKeys): Type;
 
+	public function spliceArray(Type $offsetType, Type $lengthType, Type $replacementType): Type;
+
 	/**
 	 * @return list<EnumCaseObjectType>
 	 */

src/Type/UnionType.php

@@ -790,6 +790,11 @@ public function sliceArray(Type $offsetType, Type $lengthType, TrinaryLogic $pre
 		return $this->unionTypes(static fn (Type $type): Type => $type->sliceArray($offsetType, $lengthType, $preserveKeys));
 	}
 
+	public function spliceArray(Type $offsetType, Type $lengthType, Type $replacementType): Type
+	{
+		return $this->unionTypes(static fn (Type $type): Type => $type->spliceArray($offsetType, $lengthType, $replacementType));
+	}
+
 	public function getEnumCases(): array
 	{
 		return $this->pickFromTypes(