How can I add a new comment?

[jkraai]

Using a custom rule, I'd like to add comments before certain nodes to signal a need to manually examine the current node.

Thank you!

[samsonasik]

It depends on what you want to achieve, if only add, which means replace if any exists, you can do:

 $node->setDocComment(new Doc("/** test **/"));

ensure that $node is a \PhpParser\Node\Stmt instance.

[jkraai]

@samsonasik Thank you for a good start. How can we make this work for rectoring PHP 7.x to 8.x

final class IsResourceRector extends AbstractRector implements MinPhpVersionInterface
{
    public function getRuleDefinition() : RuleDefinition
    {
        return new RuleDefinition(
            'Flag is_resource($arg) with a comment to prompt for later review',
            [new CodeSample('is_resource($arg)', '/** TODO: review is_resource **/ is_resource($arg)')]
        );
    }
    /**
     * @return array<class-string<Node>>
     */
    public function getNodeTypes() : array
    {
        return [FuncCall::class];
    }
    /**
     * @param FuncCall $node
     */
    public function refactor(Node $node) : ?Node
    {
        if (!$this->isName($node, 'is_resource')) {
            return null;
        }
        if ($node->isFirstClassCallable()) {
            return null;
        }
        $node->setDocComment(new Doc('/** TODO: review is_resource **/ '));
        return $node;
    }
    public function provideMinPhpVersion() : int
    {
        return PhpVersionFeature::EXP_OPERATOR;
    }
}

[samsonasik]

comment is living on Stmt or Param, for your use case, You need to replace whole Expresssion for that:

First, define the node types as Expression stmt:

    public function getNodeTypes(): array
    {
        return [\PhpParser\Node\Stmt\Expression::class];
    }

Next, verify if the node expr is match with FuncCall

    /**
     * @param \PhpParser\Node\Stmt\Expression $node
     */
    public function refactor(Node $node): ?Node
    {
        if (! $node->expr instanceof \PhpParser\Node\Expr\FuncCall) {
            return null;
        }

        if (! $this->nodeNameResolver->isName($node->expr, 'is_resource')) {
            return null;
        }        

       if ($node->expr->isFirstClassCallable()) {
            return null;
        }

        $node->setDocComment(new Doc('/** TODO: review is_resource **/ '));
        return $node;
    }

Above is pseudo code, but you have the idea :)

[jkraai]

I've found no variations of this that add a comment to the node.
Can someone please post a tested, working example?
Thank you.

[samsonasik]

You need to take on exact target Stmt you want to change, that's take time to learn ;)

https://github.com/nikic/PHP-Parser/tree/4.x/lib/PhpParser/Node/Stmt