Debugging

Sometimes the Rector crashes on exception and we need more detailed output to fix it or report a bug.

You can use --debug option, that will print nested exceptions output:

vendor/bin/rector process src/Controller --debug

This option additionally disables parallel processing for debug purposes.


Xdebug

You can also make use of xdebug:

  1. Make sure Xdebug is installed and enabled
  2. Add --xdebug option when running Rector
vendor/bin/rector process src/Controller --dry-run --xdebug

Inspecting Nodes

When you write a rule, you work with PhpParser\Node objects. Rector ships two global helper functions to inspect them right inside your rule.

print_node()

Prints the node back to PHP code. Useful to verify what a node represents:

public function refactor(Node $node): ?Node
{
    print_node($node);

    return null;
}

Output:

string(28) "$this->value = 'some value';"

It accepts a single node or an array of nodes.

dump_node()

Dumps the AST structure of the node. Useful to see the node type and its child properties, so you know what to match in your rule:

public function refactor(Node $node): ?Node
{
    dump_node($node);

    return null;
}

Output:

PhpParser\Node\Stmt\Expression(
    expr: PhpParser\Node\Expr\Assign(
        var: PhpParser\Node\Expr\PropertyFetch(
            var: PhpParser\Node\Expr\Variable( name: "this" )
            name: PhpParser\Node\Identifier( name: "value" )
        )
        expr: PhpParser\Node\Scalar\String_( value: "some value" )
    )
)

It accepts a single node or an array of nodes.


Reporting a Bug with Demo

The best way to report a bug is then find the smallest possible rector.php config and single file in your project that causes the crash. Do not copy-paste the whole file, it would be miss leading. The crash usually happens on a 5-10 lines of code.

When you identify those, use https://getrector.com/demo to create a reproducer.

Then you can create an an issue or even a tests. Just click on the button on the right under the code.