Add array_chunk() throw type extension

PhpStorm stubs now declare @throws \ValueError on array_chunk(), which made
every call an explicit throw point. It is thrown only when $length is less
than 1, even for an empty array, and PHP 7 only warns. The decision reads the
native type of $length, so a PHPDoc-only positive-int keeps the ValueError.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Dhb4ssXuKVWcVBcNFpsdn7

Author: ondrejmirtes

src/Type/Php/ArrayChunkFunctionThrowTypeExtension.php

@@ -0,0 +1,56 @@
+<?php declare(strict_types = 1);
+
+namespace PHPStan\Type\Php;
+
+use PhpParser\Node\Expr\FuncCall;
+use PHPStan\Analyser\Scope;
+use PHPStan\DependencyInjection\AutowiredService;
+use PHPStan\Php\PhpVersion;
+use PHPStan\Reflection\FunctionReflection;
+use PHPStan\Type\DynamicFunctionThrowTypeExtension;
+use PHPStan\Type\IntegerRangeType;
+use PHPStan\Type\Type;
+use PHPStan\Type\VoidType;
+use function count;
+
+/**
+ * array_chunk() throws ValueError only when $length is less than 1, even for an empty array.
+ */
+#[AutowiredService]
+final class ArrayChunkFunctionThrowTypeExtension implements DynamicFunctionThrowTypeExtension
+{
+
+	public function __construct(private PhpVersion $phpVersion)
+	{
+	}
+
+	public function isFunctionSupported(FunctionReflection $functionReflection): bool
+	{
+		return $functionReflection->getName() === 'array_chunk';
+	}
+
+	public function getThrowTypeFromFunctionCall(FunctionReflection $functionReflection, FuncCall $funcCall, Scope $scope): ?Type
+	{
+		if (!$this->phpVersion->throwsValueErrorForInternalFunctions()) {
+			return new VoidType();
+		}
+
+		$args = $funcCall->getArgs();
+		foreach ($args as $arg) {
+			if ($arg->unpack || $arg->name !== null) {
+				return $functionReflection->getThrowType();
+			}
+		}
+
+		if (count($args) < 2) {
+			return $functionReflection->getThrowType();
+		}
+
+		if (IntegerRangeType::fromInterval(1, null)->isSuperTypeOf($scope->getNativeType($args[1]->value))->yes()) {
+			return new VoidType();
+		}
+
+		return $functionReflection->getThrowType();
+	}
+
+}

tests/PHPStan/Rules/Exceptions/CatchWithUnthrownExceptionRuleTest.php

@@ -957,6 +957,56 @@ public function testMinMaxThrowTypeBeforePhp8(): void
 		]);
 	}
 
+	#[RequiresPhp('>= 8.0.0')]
+	public function testArrayChunkThrowType(): void
+	{
+		$this->analyse([__DIR__ . '/data/array-chunk-throw-type.php'], [
+			[
+				'Dead catch - ValueError is never thrown in the try block.',
+				15,
+			],
+			[
+				'Dead catch - ValueError is never thrown in the try block.',
+				21,
+			],
+			[
+				'Dead catch - ValueError is never thrown in the try block.',
+				46,
+			],
+		]);
+	}
+
+	#[RequiresPhp('< 8.0.0')]
+	public function testArrayChunkThrowTypeBeforePhp8(): void
+	{
+		$this->analyse([__DIR__ . '/data/array-chunk-throw-type.php'], [
+			[
+				'Dead catch - ValueError is never thrown in the try block.',
+				15,
+			],
+			[
+				'Dead catch - ValueError is never thrown in the try block.',
+				21,
+			],
+			[
+				'Dead catch - ValueError is never thrown in the try block.',
+				27,
+			],
+			[
+				'Dead catch - ValueError is never thrown in the try block.',
+				33,
+			],
+			[
+				'Dead catch - ValueError is never thrown in the try block.',
+				39,
+			],
+			[
+				'Dead catch - ValueError is never thrown in the try block.',
+				46,
+			],
+		]);
+	}
+
 	#[RequiresPhp('>= 8.0.0')]
 	public function testPrintfThrowType(): void
 	{

tests/PHPStan/Rules/Exceptions/data/array-chunk-throw-type.php

@@ -0,0 +1,52 @@
+<?php
+
+namespace ArrayChunkThrowType;
+
+class Foo
+{
+
+	/**
+	 * @param positive-int $phpDocLength
+	 */
+	public function doFoo(array $a, int $length, int $phpDocLength): void
+	{
+		try {
+			$b = array_chunk($a, 3);
+		} catch (\ValueError $e) {
+
+		}
+
+		try {
+			$b = array_chunk($a, 2, true);
+		} catch (\ValueError $e) {
+
+		}
+
+		try {
+			$b = array_chunk($a, 0);
+		} catch (\ValueError $e) {
+
+		}
+
+		try {
+			$b = array_chunk($a, $length);
+		} catch (\ValueError $e) {
+
+		}
+
+		try {
+			$b = array_chunk($a, $phpDocLength);
+		} catch (\ValueError $e) {
+
+		}
+
+		if ($length > 0) {
+			try {
+				$b = array_chunk($a, $length);
+			} catch (\ValueError $e) {
+
+			}
+		}
+	}
+
+}