Skip to content

fix(visitor): document the return types of the overridden node visitor methods - #245

Merged
lisachenko merged 2 commits into
4.xfrom
fix/node-visitor-return-annotations
Nov 2, 2026
Merged

lisachenko merged 2 commits into
4.xfrom
fix/node-visitor-return-annotations

Conversation

@lisachenko

Copy link
Copy Markdown
Member

Summary

Fixes #243. RootNamespaceNormalizer::beforeTraverse(), GeneratorDetector::enterNode() and StaticVariablesCollector::enterNode() replace {@inheritDoc} with an explicit @return docblock. That silences Symfony's DebugClassLoader "might add a native return type" deprecation. No native return types are declared, so PHP-Parser stays in charge of these signatures if it adds native types later.

Targets 4.x; cascade-merge.yml carries it into master after the merge.

Changes

  • Explicit @return (and a one-line description) on the three overridden visitor methods:
    • Node[]|null for beforeTraverse()
    • int|null for the two enterNode(), which only return DONT_TRAVERSE_CHILDREN or null
  • tests/NodeVisitor/NodeVisitorReturnTypeTest.php: every PhpParser\NodeVisitor method overridden in src/NodeVisitor has a @return tag and no native return type, so the decision is enforced for future visitors too.

Testing

  • The new test fails on 4.x without the change (3 failures) and passes with it.
  • Symfony 8.1 DebugClassLoader against the three classes: 3 deprecations before, none after.
  • vendor/bin/phpunit: OK (13750 tests; the 133 skipped and 2 incomplete are already on 4.x).
  • vendor/bin/phpstan analyse src: 1 error, which 4.x already has without this change: Traits/ReflectionClassLikeTrait.php:1303, "Strict comparison using === between (int|string) and null will always evaluate to false" (PHPStan 2.3.4).

Generated by Claude Code

…r 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 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FxhC1DaSZY1jAz2XfyjhPa

Copy link
Copy Markdown
Member Author

PHPStan analysis will fail here, but not because of this PR. The only error is Traits/ReflectionClassLikeTrait.php:1303 ("Strict comparison using === between (int|string) and null will always evaluate to false"), in code this PR doesn't touch, and 4.x itself is red with it (the last PHPStan run on its head, 1f096af). The fix is in #247, against 4.x; once it is merged, this PR is green after merging 4.x in.


Generated by Claude Code

@lisachenko
lisachenko marked this pull request as ready for review November 2, 2026 17:27
@lisachenko
lisachenko merged commit 2020b6f into 4.x Nov 2, 2026
7 checks passed
@lisachenko
lisachenko deleted the fix/node-visitor-return-annotations branch November 2, 2026 17:28
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Development

Successfully merging this pull request may close these issues.

2 participants