From 9239d0f0563cd5aaaed6194dde57bd5928dbb23d Mon Sep 17 00:00:00 2001 From: "ondrej@mirtes.cz" Date: Sun, 15 Nov 2026 14:42:30 +0000 Subject: [PATCH] Report deprecated return in finally block on PHP 8.6 PHP 8.6 deprecates returning from a finally block at compile time. Like PHP, the rule looks for return statements lexically in the finally block, including nested try and catch blocks, but not in closures, arrow functions, anonymous classes or nested function declarations. A nested try's own finally block is reported by its own TryCatch node. Amp-Thread-ID: https://ampcode.com/threads/T-01a1dfa1-37b0-77d8-96bc-e3bdf810d9d7 --- src/Php/PhpVersions.php | 5 + src/Rules/Exceptions/ReturnInFinallyRule.php | 88 ++++++++++++++ .../Exceptions/ReturnInFinallyRuleTest.php | 86 ++++++++++++++ .../data/return-in-finally-php-version.neon | 4 + .../Exceptions/data/return-in-finally.php | 112 ++++++++++++++++++ 5 files changed, 295 insertions(+) create mode 100644 src/Rules/Exceptions/ReturnInFinallyRule.php create mode 100644 tests/PHPStan/Rules/Exceptions/ReturnInFinallyRuleTest.php create mode 100644 tests/PHPStan/Rules/Exceptions/data/return-in-finally-php-version.neon create mode 100644 tests/PHPStan/Rules/Exceptions/data/return-in-finally.php diff --git a/src/Php/PhpVersions.php b/src/Php/PhpVersions.php index ee830d16bee..893dbc8fa28 100644 --- a/src/Php/PhpVersions.php +++ b/src/Php/PhpVersions.php @@ -254,6 +254,11 @@ public function deprecatesBacktickOperator(): TrinaryLogic return IntegerRangeType::fromInterval(80500, null)->isSuperTypeOf($this->phpVersions)->result; } + public function deprecatesReturnInFinally(): TrinaryLogic + { + return IntegerRangeType::fromInterval(80600, null)->isSuperTypeOf($this->phpVersions)->result; + } + public function deprecatesDecOnNonNumericString(): TrinaryLogic { return IntegerRangeType::fromInterval(80300, null)->isSuperTypeOf($this->phpVersions)->result; diff --git a/src/Rules/Exceptions/ReturnInFinallyRule.php b/src/Rules/Exceptions/ReturnInFinallyRule.php new file mode 100644 index 00000000000..d466c58e1fa --- /dev/null +++ b/src/Rules/Exceptions/ReturnInFinallyRule.php @@ -0,0 +1,88 @@ + + */ +#[RegisteredRule(level: 0)] +final class ReturnInFinallyRule implements Rule +{ + + public function __construct( + #[AutowiredParameter(ref: '%featureToggles.checkWholePhpVersionRange%')] + private bool $checkWholePhpVersionRange, + ) + { + } + + public function getNodeType(): string + { + return Stmt\TryCatch::class; + } + + public function processNode(Node $node, Scope $scope): array + { + if ($node->finally === null) { + return []; + } + + $deprecatesReturnInFinally = $scope->getPhpVersion()->deprecatesReturnInFinally(); + if ($this->checkWholePhpVersionRange ? $deprecatesReturnInFinally->no() : !$deprecatesReturnInFinally->yes()) { + return []; + } + + $errors = []; + foreach ($this->findReturns($node->finally->stmts) as $return) { + $errors[] = RuleErrorBuilder::message('Returning from a finally block is deprecated in PHP 8.6.') + ->line($return->getStartLine()) + ->identifier('finally.deprecatedReturn') + ->build(); + } + + return $errors; + } + + /** + * Like PHP, looks for return statements lexically, without descending into + * functions, classes, and expressions (which is where closures live). + * A nested try's own finally block is left out because this rule reports it separately. + * + * @param Node[] $nodes + * @return list + */ + private function findReturns(array $nodes): array + { + $returns = []; + foreach ($nodes as $node) { + if (!$node instanceof Stmt || $node instanceof Stmt\Function_ || $node instanceof Stmt\ClassLike) { + continue; + } + + if ($node instanceof Stmt\Return_) { + $returns[] = $node; + continue; + } + + $subNodeNames = $node instanceof Stmt\TryCatch ? ['stmts', 'catches'] : $node->getSubNodeNames(); + foreach ($subNodeNames as $subNodeName) { + $subNode = $node->$subNodeName; + foreach ($this->findReturns(is_array($subNode) ? $subNode : [$subNode]) as $return) { + $returns[] = $return; + } + } + } + + return $returns; + } + +} diff --git a/tests/PHPStan/Rules/Exceptions/ReturnInFinallyRuleTest.php b/tests/PHPStan/Rules/Exceptions/ReturnInFinallyRuleTest.php new file mode 100644 index 00000000000..a5361ca0713 --- /dev/null +++ b/tests/PHPStan/Rules/Exceptions/ReturnInFinallyRuleTest.php @@ -0,0 +1,86 @@ + + */ +class ReturnInFinallyRuleTest extends RuleTestCase +{ + + private bool $checkWholePhpVersionRange; + + protected function getRule(): Rule + { + return new ReturnInFinallyRule($this->checkWholePhpVersionRange); + } + + public function testRuleWithWholePhpVersionRange(): void + { + $this->checkWholePhpVersionRange = true; + $this->analyse([__DIR__ . '/data/return-in-finally.php'], [ + [ + 'Returning from a finally block is deprecated in PHP 8.6.', + 9, + ], + [ + 'Returning from a finally block is deprecated in PHP 8.6.', + 17, + ], + [ + 'Returning from a finally block is deprecated in PHP 8.6.', + 53, + ], + [ + 'Returning from a finally block is deprecated in PHP 8.6.', + 55, + ], + [ + 'Returning from a finally block is deprecated in PHP 8.6.', + 57, + ], + [ + 'Returning from a finally block is deprecated in PHP 8.6.', + 70, + ], + [ + 'Returning from a finally block is deprecated in PHP 8.6.', + 82, + ], + [ + 'Returning from a finally block is deprecated in PHP 8.6.', + 86, + ], + [ + 'Returning from a finally block is deprecated in PHP 8.6.', + 90, + ], + [ + 'Returning from a finally block is deprecated in PHP 8.6.', + 102, + ], + ]); + } + + public function testRule(): void + { + $this->checkWholePhpVersionRange = false; + $this->analyse([__DIR__ . '/data/return-in-finally.php'], [ + [ + 'Returning from a finally block is deprecated in PHP 8.6.', + 102, + ], + ]); + } + + public static function getAdditionalConfigFiles(): array + { + return [ + __DIR__ . '/data/return-in-finally-php-version.neon', + ]; + } + +} diff --git a/tests/PHPStan/Rules/Exceptions/data/return-in-finally-php-version.neon b/tests/PHPStan/Rules/Exceptions/data/return-in-finally-php-version.neon new file mode 100644 index 00000000000..37a89190078 --- /dev/null +++ b/tests/PHPStan/Rules/Exceptions/data/return-in-finally-php-version.neon @@ -0,0 +1,4 @@ +parameters: + phpVersion: + min: 80500 + max: 80600 diff --git a/tests/PHPStan/Rules/Exceptions/data/return-in-finally.php b/tests/PHPStan/Rules/Exceptions/data/return-in-finally.php new file mode 100644 index 00000000000..91a3edbcf5e --- /dev/null +++ b/tests/PHPStan/Rules/Exceptions/data/return-in-finally.php @@ -0,0 +1,112 @@ + 2; + $o = new class () { + public function foo() + { + return 3; + } + }; + } +} + +function nestedTry() +{ + try { + } finally { + try { + return 1; + } catch (\Exception $e) { + return 2; + } finally { + return 3; + } + } +} + +function closureWithTry() +{ + try { + } finally { + $f = function () { + try { + return 1; + } finally { + return 2; + } + }; + } +} + +function nestedControlFlow(array $a) +{ + try { + } finally { + foreach ($a as $v) { + if ($v) { + return 1; + } elseif ($v === 0) { + switch ($v) { + case 0: + return 2; + } + } else { + { + return 3; + } + } + } + } +} + +function phpVersionBranches() +{ + if (PHP_VERSION_ID >= 80600) { + try { + } finally { + return 1; + } + } + + if (PHP_VERSION_ID < 80600) { + try { + } finally { + return 2; + } + } +}