ondrejmirtes · Sep 22, 2026 · Sep 22, 2026
diff --git a/src/Php/PhpVersion.php b/src/Php/PhpVersion.php
@@ -246,6 +246,11 @@ public function hasStricterRoundFunctions(): bool
 		return $this->versionId >= 80000;
 	}
 
+	public function throwsValueErrorForInvalidRoundingMode(): bool
+	{
+		return $this->versionId >= 80400;
+	}
+
 	public function hasTentativeReturnTypes(): bool
 	{
 		return $this->versionId >= 80100;

diff --git a/src/Type/Php/RoundFunctionThrowTypeExtension.php b/src/Type/Php/RoundFunctionThrowTypeExtension.php
@@ -0,0 +1,63 @@
+<?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\ObjectType;
+use PHPStan\Type\Type;
+use PHPStan\Type\TypeCombinator;
+use PHPStan\Type\VoidType;
+use function count;
+
+/**
+ * round() throws ValueError only on PHP 8.4+, for an int $mode that is not
+ * one of the eight rounding modes (1-8).
+ */
+#[AutowiredService]
+final class RoundFunctionThrowTypeExtension implements DynamicFunctionThrowTypeExtension
+{
+
+	public function __construct(private PhpVersion $phpVersion)
+	{
+	}
+
+	public function isFunctionSupported(FunctionReflection $functionReflection): bool
+	{
+		return $functionReflection->getName() === 'round';
+	}
+
+	public function getThrowTypeFromFunctionCall(FunctionReflection $functionReflection, FuncCall $funcCall, Scope $scope): ?Type
+	{
+		if (!$this->phpVersion->throwsValueErrorForInvalidRoundingMode()) {
+			return new VoidType();
+		}
+
+		$args = $funcCall->getArgs();
+		foreach ($args as $arg) {
+			if ($arg->unpack || $arg->name !== null) {
+				return $functionReflection->getThrowType();
+			}
+		}
+
+		if (count($args) < 3) {
+			return new VoidType();
+		}
+
+		$validModeType = TypeCombinator::union(
+			new ObjectType('RoundingMode'),
+			IntegerRangeType::fromInterval(1, 8),
+		);
+		if ($validModeType->isSuperTypeOf($scope->getNativeType($args[2]->value))->yes()) {
+			return new VoidType();
+		}
+
+		return $functionReflection->getThrowType();
+	}
+
+}
diff --git a/tests/PHPStan/Rules/Exceptions/CatchWithUnthrownExceptionRuleTest.php b/tests/PHPStan/Rules/Exceptions/CatchWithUnthrownExceptionRuleTest.php
@@ -1180,6 +1180,72 @@ public function testPrintfThrowTypeBeforePhp8(): void
 		]);
 	}
 
+	#[RequiresPhp('>= 8.4.0')]
+	public function testRoundThrowType(): void
+	{
+		$this->analyse([__DIR__ . '/data/round-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,
+			],
+		]);
+	}
+
+	#[RequiresPhp('< 8.4.0')]
+	public function testRoundThrowTypeBeforePhp84(): void
+	{
+		$this->analyse([__DIR__ . '/data/round-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.',
+				45,
+			],
+			[
+				'Dead catch - ValueError is never thrown in the try block.',
+				51,
+			],
+			[
+				'Dead catch - ValueError is never thrown in the try block.',
+				57,
+			],
+		]);
+	}
+
 	public function testDsMapVoidThrowType(): void
 	{
 		$this->analyse([__DIR__ . '/data/ds-map-void-throw-type.php'], [

diff --git a/tests/PHPStan/Rules/Exceptions/data/round-throw-type.php b/tests/PHPStan/Rules/Exceptions/data/round-throw-type.php
@@ -0,0 +1,62 @@
+<?php
+
+namespace RoundThrowType;
+
+class Foo
+{
+
+	/**
+	 * @param 1 $phpDocMode
+	 */
+	public function doFoo(float $f, int $mode, int $phpDocMode): void
+	{
+		try {
+			$a = round($f);
+		} catch (\ValueError $e) {
+
+		}
+
+		try {
+			$a = round($f, 2);
+		} catch (\ValueError $e) {
+
+		}
+
+		try {
+			$a = round($f, 0, PHP_ROUND_HALF_EVEN);
+		} catch (\ValueError $e) {
+
+		}
+
+		try {
+			$a = round($f, 0, 8);
+		} catch (\ValueError $e) {
+
+		}
+
+		try {
+			$a = round($f, 0, \RoundingMode::HalfEven);
+		} catch (\ValueError $e) {
+
+		}
+
+		try {
+			$a = round($f, 0, 9);
+		} catch (\ValueError $e) {
+
+		}
+
+		try {
+			$a = round($f, 0, $mode);
+		} catch (\ValueError $e) {
+
+		}
+
+		try {
+			$a = round($f, 0, $phpDocMode);
+		} catch (\ValueError $e) {
+
+		}
+	}
+
+}