From dd95bc5192fa649fcad6794e7839c1bb793a840f Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 2 Nov 2026 17:14:10 +0000 Subject: [PATCH] fix(visitor): document the return types of the overridden node visitor methods PhpParser\NodeVisitor declares its return types in docblocks only. Visitor methods without a native return type and without their own @return made Symfony's DebugClassLoader report a "might add a native return type" deprecation for every application that reflects code in debug mode. The methods now document their return types instead of inheriting the docblock; no native types are declared, so PHP-Parser stays in charge of them. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01FxhC1DaSZY1jAz2XfyjhPa --- src/NodeVisitor/GeneratorDetector.php | 7 +- src/NodeVisitor/RootNamespaceNormalizer.php | 9 ++- src/NodeVisitor/StaticVariablesCollector.php | 7 +- .../NodeVisitor/NodeVisitorReturnTypeTest.php | 64 +++++++++++++++++++ 4 files changed, 84 insertions(+), 3 deletions(-) create mode 100644 tests/NodeVisitor/NodeVisitorReturnTypeTest.php diff --git a/src/NodeVisitor/GeneratorDetector.php b/src/NodeVisitor/GeneratorDetector.php index 906daa4..7d13394 100644 --- a/src/NodeVisitor/GeneratorDetector.php +++ b/src/NodeVisitor/GeneratorDetector.php @@ -23,7 +23,12 @@ class GeneratorDetector extends NodeVisitorAbstract private bool $isGenerator = false; /** - * {@inheritDoc} + * Detects yield expressions, without looking into closures + * + * The return type is declared in the docblock only, like in PhpParser\NodeVisitor: an explicit @return keeps + * Symfony's DebugClassLoader from reporting the tentative return type of the parent method. + * + * @return int|null self::DONT_TRAVERSE_CHILDREN for closures, null otherwise */ public function enterNode(Node $node) { diff --git a/src/NodeVisitor/RootNamespaceNormalizer.php b/src/NodeVisitor/RootNamespaceNormalizer.php index b412065..3280011 100644 --- a/src/NodeVisitor/RootNamespaceNormalizer.php +++ b/src/NodeVisitor/RootNamespaceNormalizer.php @@ -25,7 +25,14 @@ class RootNamespaceNormalizer extends NodeVisitorAbstract { /** - * {@inheritdoc} + * Wraps the statements of a file without a namespace into a global namespace node + * + * The return type is declared in the docblock only, like in PhpParser\NodeVisitor: an explicit @return keeps + * Symfony's DebugClassLoader from reporting the tentative return type of the parent method. + * + * @param \PhpParser\Node[] $nodes + * + * @return \PhpParser\Node[]|null Null when the file declares namespaces itself */ public function beforeTraverse(array $nodes) { diff --git a/src/NodeVisitor/StaticVariablesCollector.php b/src/NodeVisitor/StaticVariablesCollector.php index 2e01588..f218f06 100644 --- a/src/NodeVisitor/StaticVariablesCollector.php +++ b/src/NodeVisitor/StaticVariablesCollector.php @@ -45,7 +45,12 @@ public function __construct(\ReflectionClass|\ReflectionFunction|\ReflectionMeth } /** - * {@inheritDoc} + * Collects static variables with their default values, without looking into closures + * + * The return type is declared in the docblock only, like in PhpParser\NodeVisitor: an explicit @return keeps + * Symfony's DebugClassLoader from reporting the tentative return type of the parent method. + * + * @return int|null self::DONT_TRAVERSE_CHILDREN for closures, null otherwise */ public function enterNode(Node $node) { diff --git a/tests/NodeVisitor/NodeVisitorReturnTypeTest.php b/tests/NodeVisitor/NodeVisitorReturnTypeTest.php new file mode 100644 index 0000000..edb087d --- /dev/null +++ b/tests/NodeVisitor/NodeVisitorReturnTypeTest.php @@ -0,0 +1,64 @@ + + * + * This source file is subject to the license that is bundled + * with this source code in the file LICENSE. + */ + +namespace Go\ParserReflection\NodeVisitor; + +use PhpParser\NodeVisitor; +use PHPUnit\Framework\Attributes\DataProvider; +use PHPUnit\Framework\TestCase; +use ReflectionClass; + +/** + * PhpParser\NodeVisitor declares the return types of its methods in docblocks only. An implementation without a + * native return type and without its own @return makes Symfony's DebugClassLoader report that the parent "might + * add" a native return type, so every overridden visitor method documents its return type explicitly. + */ +final class NodeVisitorReturnTypeTest extends TestCase +{ + /** + * @param class-string $visitorClass + */ + #[DataProvider('visitorMethods')] + public function testOverriddenVisitorMethodsDocumentTheirReturnType(string $visitorClass, string $methodName): void + { + $method = new ReflectionClass($visitorClass)->getMethod($methodName); + $this->assertFalse($method->hasReturnType(), 'The return type is documented, not declared: PhpParser\NodeVisitor owns it'); + + $docComment = $method->getDocComment(); + $this->assertIsString($docComment); + $this->assertMatchesRegularExpression('/@return\s+\S+/', $docComment); + } + + /** + * @return iterable, string}> + */ + public static function visitorMethods(): iterable + { + $visitorMethods = array_map( + static fn (\ReflectionMethod $method): string => $method->getName(), + new ReflectionClass(NodeVisitor::class)->getMethods() + ); + foreach (glob(dirname(__DIR__, 2) . '/src/NodeVisitor/*.php') ?: [] as $file) { + /** @var class-string $visitorClass */ + $visitorClass = __NAMESPACE__ . '\\' . basename($file, '.php'); + $visitor = new ReflectionClass($visitorClass); + if (!$visitor->implementsInterface(NodeVisitor::class)) { + continue; + } + foreach ($visitorMethods as $methodName) { + if ($visitor->getMethod($methodName)->getDeclaringClass()->getName() === $visitorClass) { + yield $visitor->getShortName() . '::' . $methodName => [$visitorClass, $methodName]; + } + } + } + } +}