From 54184aac14c5bdb3ad61ef9f0e45f3a5c74fb48f Mon Sep 17 00:00:00 2001 From: USAMI Kenta Date: Wed, 23 Sep 2026 05:59:20 +0900 Subject: [PATCH 1/4] Add range() throw type extension PhpStorm stubs declare `@throws \ValueError` on range(), so every call became an explicit throw point and a catch around a valid call was never reported as dead. The extension returns void on PHP 7, which does not throw, and on PHP 8 when the native argument types are constant numbers or strings, RangeFunctionArgumentsHelper finds that no analysed PHP version rejects them, and the range has fewer items than RANGE_SIZE_LIMIT, the HT_MAX_SIZE of a 32-bit PHP. A range whose number of items does not fit into a float keeps the throw point as well. Co-authored-by: Claude Opus 5.5 --- build/baseline-pre-8.0.neon | 6 + .../Php/RangeFunctionReturnTypeExtension.php | 2 +- .../Php/RangeFunctionThrowTypeExtension.php | 118 +++++++++++++++++ .../CatchWithUnthrownExceptionRuleTest.php | 110 ++++++++++++++++ .../Exceptions/data/range-throw-type.php | 121 ++++++++++++++++++ 5 files changed, 356 insertions(+), 1 deletion(-) create mode 100644 src/Type/Php/RangeFunctionThrowTypeExtension.php create mode 100644 tests/PHPStan/Rules/Exceptions/data/range-throw-type.php diff --git a/build/baseline-pre-8.0.neon b/build/baseline-pre-8.0.neon index 0e94aa40013..a59e5c583a4 100644 --- a/build/baseline-pre-8.0.neon +++ b/build/baseline-pre-8.0.neon @@ -265,3 +265,9 @@ parameters: identifier: property.internalClass count: 3 path: ../src/Analyser/Ignore/LineIgnoreFixer.php + + - + rawMessage: 'Dead catch - ValueError is never thrown in the try block.' + identifier: catch.neverThrown + count: 1 + path: ../src/Type/Php/RangeFunctionArgumentsHelper.php diff --git a/src/Type/Php/RangeFunctionReturnTypeExtension.php b/src/Type/Php/RangeFunctionReturnTypeExtension.php index 2c78439d7c2..64ea02da531 100644 --- a/src/Type/Php/RangeFunctionReturnTypeExtension.php +++ b/src/Type/Php/RangeFunctionReturnTypeExtension.php @@ -212,7 +212,7 @@ private static function getGeneralType(Type $startType, Type $endType, Type $ste * only calling it tells - for a character range, which has at most 256 * items, and for a zero, infinite or NAN argument, for which it throws. */ - private static function getRangeLength(int|float|string $start, int|float|string $end, int|float $step): ?float + public static function getRangeLength(int|float|string $start, int|float|string $end, int|float $step): ?float { if (is_string($start) && is_string($end) && !is_numeric($start) && !is_numeric($end)) { return null; diff --git a/src/Type/Php/RangeFunctionThrowTypeExtension.php b/src/Type/Php/RangeFunctionThrowTypeExtension.php new file mode 100644 index 00000000000..2c003721f5c --- /dev/null +++ b/src/Type/Php/RangeFunctionThrowTypeExtension.php @@ -0,0 +1,118 @@ +getName() === 'range'; + } + + public function getThrowTypeFromFunctionCall(FunctionReflection $functionReflection, FuncCall $funcCall, Scope $scope): ?Type + { + // PHP 7 reported these with a warning and a false return value + $phpVersions = $scope->getPhpVersion(); + if ($phpVersions->throwsValueErrorForInternalFunctions()->no()) { + 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(); + } + + $starts = self::getConstantValues($scope->getNativeType($args[0]->value), true); + $ends = self::getConstantValues($scope->getNativeType($args[1]->value), true); + $steps = count($args) >= 3 ? self::getConstantValues($scope->getNativeType($args[2]->value), false) : [1]; + if ($starts === null || $ends === null || $steps === null) { + return $functionReflection->getThrowType(); + } + + $hasStricterRange = $phpVersions->hasStricterRangeFunction(); + foreach ($starts as $start) { + foreach ($ends as $end) { + foreach ($steps as $step) { + if (self::mightThrow($hasStricterRange, $start, $end, $step)) { + return $functionReflection->getThrowType(); + } + } + } + } + + return new VoidType(); + } + + /** + * @return ($allowString is true ? list : list)|null + */ + private static function getConstantValues(Type $type, bool $allowString): ?array + { + if (!$type->isConstantScalarValue()->yes()) { + return null; + } + + $values = []; + foreach ($type->getConstantScalarValues() as $value) { + if (!is_int($value) && !is_float($value) && (!$allowString || !is_string($value))) { + return null; + } + + $values[] = $value; + } + + return $values; + } + + private static function mightThrow(TrinaryLogic $hasStricterRange, int|float|string $start, int|float|string $end, int|float $step): bool + { + $length = RangeFunctionReturnTypeExtension::getRangeLength($start, $end, $step); + if ($length === null) { + // only a character range has no number of items, any other one did not fit into a float + if (!is_string($start) || !is_string($end) || is_numeric($start) || is_numeric($end)) { + return true; + } + } elseif ($length >= self::RANGE_SIZE_LIMIT) { + return true; + } + + // calling range() tells about the step and the boundaries of a short range + $runtimeRejects = null; + if ($length === null || $length <= ConstantArrayTypeBuilder::ARRAY_COUNT_LIMIT) { + $runtimeRejects = RangeFunctionArgumentsHelper::callRange($start, $end, $step) === false; + } + + return !RangeFunctionArgumentsHelper::rejects($hasStricterRange, $start, $end, $step, $runtimeRejects)->no(); + } + +} diff --git a/tests/PHPStan/Rules/Exceptions/CatchWithUnthrownExceptionRuleTest.php b/tests/PHPStan/Rules/Exceptions/CatchWithUnthrownExceptionRuleTest.php index d43a9500e84..254fe939361 100644 --- a/tests/PHPStan/Rules/Exceptions/CatchWithUnthrownExceptionRuleTest.php +++ b/tests/PHPStan/Rules/Exceptions/CatchWithUnthrownExceptionRuleTest.php @@ -10,6 +10,7 @@ use PHPStan\Testing\CompositeRule; use PHPStan\Testing\RuleTestCase; use PHPUnit\Framework\Attributes\RequiresPhp; +use const PHP_VERSION_ID; /** * @extends RuleTestCase @@ -1565,4 +1566,113 @@ public function testUnserializeThrowTypeBeforePhp8(): void ]); } + #[RequiresPhp('>= 8.0.0')] + public function testRangeThrowType(): void + { + $errors = [ + [ + 'Dead catch - ValueError is never thrown in the try block.', + 14, + ], + [ + 'Dead catch - ValueError is never thrown in the try block.', + 23, + ], + [ + 'Dead catch - ValueError is never thrown in the try block.', + 29, + ], + [ + 'Dead catch - ValueError is never thrown in the try block.', + 35, + ], + ]; + + // the helper decides a character range by the PHP 8.3 rules only when it runs on PHP 8.3 or newer + if (PHP_VERSION_ID >= 80300) { + $errors[] = [ + 'Dead catch - ValueError is never thrown in the try block.', + 60, + ]; + } + + $errors[] = [ + 'Dead catch - ValueError is never thrown in the try block.', + 88, + ]; + + $this->analyse([__DIR__ . '/data/range-throw-type.php'], $errors); + } + + #[RequiresPhp('< 8.0.0')] + public function testRangeThrowTypeBeforePhp8(): void + { + $this->analyse([__DIR__ . '/data/range-throw-type.php'], [ + [ + 'Dead catch - ValueError is never thrown in the try block.', + 14, + ], + [ + 'Dead catch - ValueError is never thrown in the try block.', + 23, + ], + [ + 'Dead catch - ValueError is never thrown in the try block.', + 29, + ], + [ + 'Dead catch - ValueError is never thrown in the try block.', + 35, + ], + [ + 'Dead catch - ValueError is never thrown in the try block.', + 41, + ], + [ + 'Dead catch - ValueError is never thrown in the try block.', + 47, + ], + [ + 'Dead catch - ValueError is never thrown in the try block.', + 53, + ], + [ + 'Dead catch - ValueError is never thrown in the try block.', + 60, + ], + [ + 'Dead catch - ValueError is never thrown in the try block.', + 67, + ], + [ + 'Dead catch - ValueError is never thrown in the try block.', + 74, + ], + [ + 'Dead catch - ValueError is never thrown in the try block.', + 81, + ], + [ + 'Dead catch - ValueError is never thrown in the try block.', + 88, + ], + [ + 'Dead catch - ValueError is never thrown in the try block.', + 95, + ], + [ + 'Dead catch - ValueError is never thrown in the try block.', + 102, + ], + [ + 'Dead catch - ValueError is never thrown in the try block.', + 109, + ], + [ + 'Dead catch - ValueError is never thrown in the try block.', + 115, + ], + ]); + } + } diff --git a/tests/PHPStan/Rules/Exceptions/data/range-throw-type.php b/tests/PHPStan/Rules/Exceptions/data/range-throw-type.php new file mode 100644 index 00000000000..e5e7b611fe6 --- /dev/null +++ b/tests/PHPStan/Rules/Exceptions/data/range-throw-type.php @@ -0,0 +1,121 @@ += 80300) { + try { + $a = range('a', 'z'); + } catch (\ValueError $e) { + + } + + // PHP 8.3 rejects a negative step on an increasing range + try { + $a = range(1, 1000, -1); + } catch (\ValueError $e) { + + } + + // PHP 8.3 builds a character range, in which 2 exceeds the range from '9' to ':' + try { + $a = range('9', ':', 2); + } catch (\ValueError $e) { + + } + + // PHP 8.3 compares an integral float step exactly, and 2 ** 60 exceeds the range up to 2 ** 60 - 1 + try { + $a = range(0, 1152921504606846975, 1152921504606846976.0); + } catch (\ValueError $e) { + + } + } else { + // the sign of the step used to be ignored + try { + $a = range(1, 1000, -1); + } catch (\ValueError $e) { + + } + + // '1' used to be a number next to a non-numeric string, so the step exceeds the range 1..0 + try { + $a = range('1', 'a', 30); + } catch (\ValueError $e) { + + } + + // integers are compared exactly, and 2 ** 60 exceeds the range up to 2 ** 60 - 1 + try { + $a = range(0, 1152921504606846975, 1152921504606846976); + } catch (\ValueError $e) { + + } + + // the number of items does not fit into a float, which exceeds every array size + try { + $a = range(-1.0e308, 1.0e308); + } catch (\ValueError $e) { + + } + + try { + $a = range(0, 1, 1.0e-320); + } catch (\ValueError $e) { + + } + } + } + +} From bc911125f3007da0602725a7078bb22227782a85 Mon Sep 17 00:00:00 2001 From: USAMI Kenta Date: Tue, 3 Nov 2026 02:16:48 +0900 Subject: [PATCH 2/4] Test the range() throw type for undecided PHP versions and boundaries A guard on both sides of PHP 8.0 leaves undecided whether range() throws a ValueError at all, and a boundary that is only partly a constant leaves the arguments undecided. Both keep the throw point. --- .../CatchWithUnthrownExceptionRuleTest.php | 8 ++++++++ .../Exceptions/data/range-throw-type.php | 20 +++++++++++++++++++ 2 files changed, 28 insertions(+) diff --git a/tests/PHPStan/Rules/Exceptions/CatchWithUnthrownExceptionRuleTest.php b/tests/PHPStan/Rules/Exceptions/CatchWithUnthrownExceptionRuleTest.php index 254fe939361..cae71dd71be 100644 --- a/tests/PHPStan/Rules/Exceptions/CatchWithUnthrownExceptionRuleTest.php +++ b/tests/PHPStan/Rules/Exceptions/CatchWithUnthrownExceptionRuleTest.php @@ -1672,6 +1672,14 @@ public function testRangeThrowTypeBeforePhp8(): void 'Dead catch - ValueError is never thrown in the try block.', 115, ], + [ + 'Dead catch - ValueError is never thrown in the try block.', + 128, + ], + [ + 'Dead catch - ValueError is never thrown in the try block.', + 136, + ], ]); } diff --git a/tests/PHPStan/Rules/Exceptions/data/range-throw-type.php b/tests/PHPStan/Rules/Exceptions/data/range-throw-type.php index e5e7b611fe6..45bcefc8bff 100644 --- a/tests/PHPStan/Rules/Exceptions/data/range-throw-type.php +++ b/tests/PHPStan/Rules/Exceptions/data/range-throw-type.php @@ -118,4 +118,24 @@ public function doFoo(int $i): void } } + public function doBar(bool $flag, string $s): void + { + // a guard with an upper bound only would leave the analysed PHP version at 8.0 + if (PHP_VERSION_ID >= 70400 && PHP_VERSION_ID < 80100) { + // PHP 7 does not throw, PHP 8.0 does + try { + $a = range(1, 10, 0); + } catch (\ValueError $e) { + + } + } + + // only a part of the boundary is a constant + try { + $a = range($flag ? 1 : $s, 10); + } catch (\ValueError $e) { + + } + } + } From 5789d3666516d29ed415333ea981f696f13a521d Mon Sep 17 00:00:00 2001 From: USAMI Kenta Date: Sat, 14 Nov 2026 04:16:15 +0900 Subject: [PATCH 3/4] Keep the ValueError of range() for a PHP version range that starts before PHP 8 The reflection of range() has no @throws when the analysed PHP version range starts before PHP 8, so returning its throw type left the call without a throw point, and catches around a call that throws on PHP 8 were reported as dead. --- .../Php/RangeFunctionThrowTypeExtension.php | 21 ++++++++++++++----- .../unthrown-exception-php-version-range.php | 18 ++++++++++++++++ 2 files changed, 34 insertions(+), 5 deletions(-) diff --git a/src/Type/Php/RangeFunctionThrowTypeExtension.php b/src/Type/Php/RangeFunctionThrowTypeExtension.php index 2c003721f5c..67ba0462cb5 100644 --- a/src/Type/Php/RangeFunctionThrowTypeExtension.php +++ b/src/Type/Php/RangeFunctionThrowTypeExtension.php @@ -9,8 +9,10 @@ use PHPStan\TrinaryLogic; use PHPStan\Type\Constant\ConstantArrayTypeBuilder; use PHPStan\Type\DynamicFunctionThrowTypeExtension; +use PHPStan\Type\ObjectType; use PHPStan\Type\Type; use PHPStan\Type\VoidType; +use ValueError; use function count; use function is_float; use function is_int; @@ -33,7 +35,7 @@ public function isFunctionSupported(FunctionReflection $functionReflection): boo return $functionReflection->getName() === 'range'; } - public function getThrowTypeFromFunctionCall(FunctionReflection $functionReflection, FuncCall $funcCall, Scope $scope): ?Type + public function getThrowTypeFromFunctionCall(FunctionReflection $functionReflection, FuncCall $funcCall, Scope $scope): Type { // PHP 7 reported these with a warning and a false return value $phpVersions = $scope->getPhpVersion(); @@ -44,19 +46,19 @@ public function getThrowTypeFromFunctionCall(FunctionReflection $functionReflect $args = $funcCall->getArgs(); foreach ($args as $arg) { if ($arg->unpack || $arg->name !== null) { - return $functionReflection->getThrowType(); + return self::getDeclaredThrowType($functionReflection); } } if (count($args) < 2) { - return $functionReflection->getThrowType(); + return self::getDeclaredThrowType($functionReflection); } $starts = self::getConstantValues($scope->getNativeType($args[0]->value), true); $ends = self::getConstantValues($scope->getNativeType($args[1]->value), true); $steps = count($args) >= 3 ? self::getConstantValues($scope->getNativeType($args[2]->value), false) : [1]; if ($starts === null || $ends === null || $steps === null) { - return $functionReflection->getThrowType(); + return self::getDeclaredThrowType($functionReflection); } $hasStricterRange = $phpVersions->hasStricterRangeFunction(); @@ -64,7 +66,7 @@ public function getThrowTypeFromFunctionCall(FunctionReflection $functionReflect foreach ($ends as $end) { foreach ($steps as $step) { if (self::mightThrow($hasStricterRange, $start, $end, $step)) { - return $functionReflection->getThrowType(); + return self::getDeclaredThrowType($functionReflection); } } } @@ -73,6 +75,15 @@ public function getThrowTypeFromFunctionCall(FunctionReflection $functionReflect return new VoidType(); } + /** + * The reflection of a PHP version range that starts before PHP 8 has no @throws, + * but range() throws on the PHP 8 versions in it. + */ + private static function getDeclaredThrowType(FunctionReflection $functionReflection): Type + { + return $functionReflection->getThrowType() ?? new ObjectType(ValueError::class); + } + /** * @return ($allowString is true ? list : list)|null */ diff --git a/tests/PHPStan/Rules/Exceptions/data/unthrown-exception-php-version-range.php b/tests/PHPStan/Rules/Exceptions/data/unthrown-exception-php-version-range.php index fc8496598b0..812e2c652a4 100644 --- a/tests/PHPStan/Rules/Exceptions/data/unthrown-exception-php-version-range.php +++ b/tests/PHPStan/Rules/Exceptions/data/unthrown-exception-php-version-range.php @@ -56,4 +56,22 @@ public function stringCast(ThrowsOnToString $o): string } } + public function rangeWithInvalidStep(): void + { + try { + range(1, 10, 0); + } catch (\ValueError $e) { // PHP 8 throws, PHP 7 returns false + + } + } + + public function rangeWithUnknownBoundary(int $i): void + { + try { + range(1, $i); + } catch (\ValueError $e) { // a range too long for an array throws on PHP 8 + + } + } + } From dbdb6b949aee9fb76dd6b0424f1ec8ecf2b38eda Mon Sep 17 00:00:00 2001 From: USAMI Kenta Date: Sat, 14 Nov 2026 05:16:03 +0900 Subject: [PATCH 4/4] Expect the ValueError of range() after a PHP 8 guard when analysing on PHP 7 After if (PHP_VERSION_ID < 80000) { return; } the rest of the method is analysed as PHP 8 with the reflection of PHP 7, which has no @throws. Since the ValueError fallback, the catches around the calls that throw on PHP 8 are no longer dead there. --- .../CatchWithUnthrownExceptionRuleTest.php | 48 ------------------- 1 file changed, 48 deletions(-) diff --git a/tests/PHPStan/Rules/Exceptions/CatchWithUnthrownExceptionRuleTest.php b/tests/PHPStan/Rules/Exceptions/CatchWithUnthrownExceptionRuleTest.php index cae71dd71be..4cda7f9c7e8 100644 --- a/tests/PHPStan/Rules/Exceptions/CatchWithUnthrownExceptionRuleTest.php +++ b/tests/PHPStan/Rules/Exceptions/CatchWithUnthrownExceptionRuleTest.php @@ -1624,58 +1624,10 @@ public function testRangeThrowTypeBeforePhp8(): void 'Dead catch - ValueError is never thrown in the try block.', 35, ], - [ - 'Dead catch - ValueError is never thrown in the try block.', - 41, - ], - [ - 'Dead catch - ValueError is never thrown in the try block.', - 47, - ], - [ - 'Dead catch - ValueError is never thrown in the try block.', - 53, - ], - [ - 'Dead catch - ValueError is never thrown in the try block.', - 60, - ], - [ - 'Dead catch - ValueError is never thrown in the try block.', - 67, - ], - [ - 'Dead catch - ValueError is never thrown in the try block.', - 74, - ], - [ - 'Dead catch - ValueError is never thrown in the try block.', - 81, - ], [ 'Dead catch - ValueError is never thrown in the try block.', 88, ], - [ - 'Dead catch - ValueError is never thrown in the try block.', - 95, - ], - [ - 'Dead catch - ValueError is never thrown in the try block.', - 102, - ], - [ - 'Dead catch - ValueError is never thrown in the try block.', - 109, - ], - [ - 'Dead catch - ValueError is never thrown in the try block.', - 115, - ], - [ - 'Dead catch - ValueError is never thrown in the try block.', - 128, - ], [ 'Dead catch - ValueError is never thrown in the try block.', 136,