Add str_split() throw type extension

PhpStorm stubs now declare @throws \ValueError on str_split(), which made
every call an explicit throw point. It is thrown only when $length is less
than 1, 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/StrSplitFunctionThrowTypeExtension.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;
+
+/**
+ * str_split() throws ValueError only when $length is less than 1.
+ */
+#[AutowiredService]
+final class StrSplitFunctionThrowTypeExtension implements DynamicFunctionThrowTypeExtension
+{
+
+	public function __construct(private PhpVersion $phpVersion)
+	{
+	}
+
+	public function isFunctionSupported(FunctionReflection $functionReflection): bool
+	{
+		return $functionReflection->getName() === 'str_split';
+	}
+
+	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 new VoidType();
+		}
+
+		if (IntegerRangeType::fromInterval(1, null)->isSuperTypeOf($scope->getNativeType($args[1]->value))->yes()) {
+			return new VoidType();
+		}
+
+		return $functionReflection->getThrowType();
+	}
+
+}

tests/PHPStan/Rules/Exceptions/CatchWithUnthrownExceptionRuleTest.php

@@ -1246,6 +1246,56 @@ public function testRoundThrowTypeBeforePhp84(): void
 		]);
 	}
 
+	#[RequiresPhp('>= 8.0.0')]
+	public function testStrSplitThrowType(): void
+	{
+		$this->analyse([__DIR__ . '/data/str-split-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 testStrSplitThrowTypeBeforePhp8(): void
+	{
+		$this->analyse([__DIR__ . '/data/str-split-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,
+			],
+		]);
+	}
+
 	public function testDsMapVoidThrowType(): void
 	{
 		$this->analyse([__DIR__ . '/data/ds-map-void-throw-type.php'], [

tests/PHPStan/Rules/Exceptions/data/str-split-throw-type.php

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