From 6b8fa1d890aa707afb8f2aa8712ca2d345cccda3 Mon Sep 17 00:00:00 2001
From: Jan Nedbal <janedbal@gmail.com>
Date: Thu, 5 Nov 2026 09:50:25 +0100
Subject: [PATCH] Expose ClassMethod and Function_ on the return-statements
 nodes

MethodReturnStatementsNode::getClassMethod() and
FunctionReturnStatementsNode::getFunction() return the parser node of the
analysed method or function. ClosureReturnStatementsNode and
PropertyHookReturnStatementsNode already expose their parser nodes.

A fixable rule on ReturnStatementsNode can now change the signature, for
example the native return type.

Co-Authored-By: Claude Code
---
 src/Node/FunctionReturnStatementsNode.php     |  5 +++
 src/Node/MethodReturnStatementsNode.php       |  5 +++
 .../ReturnStatementsNodeParserNodeRule.php    | 44 +++++++++++++++++++
 ...ReturnStatementsNodeParserNodeRuleTest.php | 37 ++++++++++++++++
 .../return-statements-node-parser-node.php    | 23 ++++++++++
 5 files changed, 114 insertions(+)
 create mode 100644 tests/PHPStan/Node/ReturnStatementsNodeParserNodeRule.php
 create mode 100644 tests/PHPStan/Node/ReturnStatementsNodeParserNodeRuleTest.php
 create mode 100644 tests/PHPStan/Node/data/return-statements-node-parser-node.php

diff --git a/src/Node/FunctionReturnStatementsNode.php b/src/Node/FunctionReturnStatementsNode.php
index 3403425697a..476ada5788c 100644
--- a/src/Node/FunctionReturnStatementsNode.php
+++ b/src/Node/FunctionReturnStatementsNode.php
@@ -42,6 +42,11 @@ public function __construct(
 		parent::__construct($function->getAttributes());
 	}
 
+	public function getFunction(): Function_
+	{
+		return $this->function;
+	}
+
 	public function getReturnStatements(): array
 	{
 		return $this->returnStatements;
diff --git a/src/Node/MethodReturnStatementsNode.php b/src/Node/MethodReturnStatementsNode.php
index 620e271dc36..adc2f9a68ad 100644
--- a/src/Node/MethodReturnStatementsNode.php
+++ b/src/Node/MethodReturnStatementsNode.php
@@ -47,6 +47,11 @@ public function __construct(
 		$this->classMethod = $method;
 	}
 
+	public function getClassMethod(): ClassMethod
+	{
+		return $this->classMethod;
+	}
+
 	public function getReturnStatements(): array
 	{
 		return $this->returnStatements;
diff --git a/tests/PHPStan/Node/ReturnStatementsNodeParserNodeRule.php b/tests/PHPStan/Node/ReturnStatementsNodeParserNodeRule.php
new file mode 100644
index 00000000000..7a7cdde13ba
--- /dev/null
+++ b/tests/PHPStan/Node/ReturnStatementsNodeParserNodeRule.php
@@ -0,0 +1,44 @@
+<?php declare(strict_types = 1);
+
+namespace PHPStan\Node;
+
+use PhpParser\Node;
+use PHPStan\Analyser\Scope;
+use PHPStan\Rules\Rule;
+use PHPStan\Rules\RuleErrorBuilder;
+use function sprintf;
+
+/**
+ * @implements Rule<ReturnStatementsNode>
+ */
+class ReturnStatementsNodeParserNodeRule implements Rule
+{
+
+	public function getNodeType(): string
+	{
+		return ReturnStatementsNode::class;
+	}
+
+	public function processNode(Node $node, Scope $scope): array
+	{
+		if ($node instanceof MethodReturnStatementsNode) {
+			$parserNode = $node->getClassMethod();
+		} elseif ($node instanceof FunctionReturnStatementsNode) {
+			$parserNode = $node->getFunction();
+		} else {
+			return [];
+		}
+
+		return [
+			RuleErrorBuilder::message(sprintf(
+				'%s %s(), lines %d-%d, return type node: %s',
+				$parserNode->getType(),
+				$parserNode->name->toString(),
+				$parserNode->getStartLine(),
+				$parserNode->getEndLine(),
+				$parserNode->returnType !== null ? $parserNode->returnType->getType() : 'none',
+			))->identifier('tests.returnStatementsNodeParserNode')->build(),
+		];
+	}
+
+}
diff --git a/tests/PHPStan/Node/ReturnStatementsNodeParserNodeRuleTest.php b/tests/PHPStan/Node/ReturnStatementsNodeParserNodeRuleTest.php
new file mode 100644
index 00000000000..a3d56cbcabe
--- /dev/null
+++ b/tests/PHPStan/Node/ReturnStatementsNodeParserNodeRuleTest.php
@@ -0,0 +1,37 @@
+<?php declare(strict_types = 1);
+
+namespace PHPStan\Node;
+
+use PHPStan\Rules\Rule;
+use PHPStan\Testing\RuleTestCase;
+
+/**
+ * @extends RuleTestCase<ReturnStatementsNodeParserNodeRule>
+ */
+class ReturnStatementsNodeParserNodeRuleTest extends RuleTestCase
+{
+
+	protected function getRule(): Rule
+	{
+		return new ReturnStatementsNodeParserNodeRule();
+	}
+
+	public function testRule(): void
+	{
+		$this->analyse([__DIR__ . '/data/return-statements-node-parser-node.php'], [
+			[
+				'Stmt_ClassMethod doFoo(), lines 8-11, return type node: NullableType',
+				8,
+			],
+			[
+				'Stmt_ClassMethod doBar(), lines 13-16, return type node: none',
+				13,
+			],
+			[
+				'Stmt_Function doBaz(), lines 20-23, return type node: Identifier',
+				20,
+			],
+		]);
+	}
+
+}
diff --git a/tests/PHPStan/Node/data/return-statements-node-parser-node.php b/tests/PHPStan/Node/data/return-statements-node-parser-node.php
new file mode 100644
index 00000000000..e51d797dcac
--- /dev/null
+++ b/tests/PHPStan/Node/data/return-statements-node-parser-node.php
@@ -0,0 +1,23 @@
+<?php
+
+namespace ReturnStatementsNodeParserNode;
+
+class Foo
+{
+
+	public function doFoo(): ?int
+	{
+		return 1;
+	}
+
+	public function doBar()
+	{
+		$f = static fn (): int => 1;
+	}
+
+}
+
+function doBaz(): int
+{
+	return 2;
+}