PHP-Parser

The parser converts PHP source code into an Abstract Syntax Tree (AST), also known as a node tree.

Supported Versions

• PHP 7 and PHP 8: Full support.
• PHP 5: PHP-Parser 5.x has limited support. Some variable expressions (like $$foo[0]) will always be interpreted using PHP 7 logic, and certain declarations like global $$var[0] will cause parse errors (though error recovery mode can mitigate this).
• Cross-version parsing: The package includes a wrapper to emulate tokens from newer PHP versions, allowing you to parse newer code (e.g., PHP 8.4) even when running on an older PHP version (e.g., 7.4).

Output Structure

An AST represents the logical structure of the code. For example, the code <?php echo 'Hi', 'World'; produces a tree structure similar to this:

array(
    0: Stmt_Echo(
        exprs: array(
            0: Scalar_String(
                value: Hi
            )
            1: Scalar_String(
                value: World
            )
        )
    )
)

In version 4.0, many subnodes that previously held simple strings now store Identifier nodes (or VarLikeIdentifier nodes if they have the form $ident).

While constructors automatically convert strings to Identifiers and Identifiers implement __toString(), you must update any code that uses:

• is_string() checks on these subnodes.
• Type-strict comparisons.
• Strict-mode operations.

Affected subnodes include:

• Const_::$name
• NullableType::$type (simple types)
• Param::$type (simple types)
• Expr\ClassConstFetch::$name
• Expr\Closure::$returnType (simple types)
• Expr\MethodCall::$name
• Expr\PropertyFetch::$name
• Expr\StaticCall::$name
• Expr\StaticPropertyFetch::$name (uses VarLikeIdentifier)
• Stmt\Class_::$name
• Stmt\ClassMethod::$name
• Stmt\ClassMethod::$returnType (simple types)
• Stmt\Function_::$name
• Stmt\Function_::$returnType (simple types)
• Stmt\Goto_::$name
• Stmt\Interface_::$name
• Stmt\Label::$name
• Stmt\PropertyProperty::$name (uses VarLikeIdentifier)
• Stmt\TraitUseAdaptation\Alias::$method
• Stmt\TraitUseAdaptation\Alias::$newName
• Stmt\TraitUseAdaptation\Precedence::$method
• Stmt\Trait_::$name
• Stmt\UseUse::$alias

The Node::getType() method returns names using underscores instead of namespace separators and does not include trailing underscores used in class names.

In version 1.0, several node classes were renamed or moved to different namespaces, which changes the string returned by Node::getType(). If your code compares getType() results to specific strings or uses them in custom pretty printers, you must update your logic to match the new mappings.

Key changes include:

• Assignment operators moved from Expr_Assign... to Expr_AssignOp_... (e.g., Expr_AssignPlus becomes Expr_AssignOp_Plus).
• Binary operators moved from Expr_... to Expr_BinaryOp_... (e.g., Expr_Plus becomes Expr_BinaryOp_Plus).
• Magic constants moved from Scalar_...Const to Scalar_MagicConst_... (e.g., Scalar_ClassConst becomes Scalar_MagicConst_Class).

// Example of mapping changes:
Expr_AssignPlus       => Expr_AssignOp_Plus
Expr_Plus              => Expr_BinaryOp_Plus
Scalar_ClassConst      => Scalar_MagicConst_Class

For automated refactoring where you want to modify only specific parts of the code while leaving the rest of the formatting untouched, use the printFormatPreserving method. This mode attempts to preserve the formatting of AST nodes that have not changed.

To use this functionality, you must follow a specific workflow:

1. Parse the original code to get statements and tokens.
2. Use a CloningVisitor to create a copy of the AST before making any modifications.
3. Modify the cloned AST.
4. Call printFormatPreserving using the new statements, the original statements, and the original tokens.

Warning: If using name resolution, you should likely disable the replaceNodes option to prevent resolved names from being written directly into the AST, which can cause unintended changes in the output.

use PhpParser\{NodeTraverser, NodeVisitor, ParserFactory, PrettyPrinter};

$parser = (new ParserFactory())->createForHostVersion();
$oldStmts = $parser->parse($code);
$oldTokens = $parser->getTokens();

// Run CloningVisitor before making changes to the AST.
$traverser = new NodeTraverser(new NodeVisitor\CloningVisitor());
$newStmts = $traverser->traverse($oldStmts);

// MODIFY $newStmts HERE

$printer = new PrettyPrinter\Standard();
$newCode = $printer->printFormatPreserving($newStmts, $oldStmts, $oldTokens);

To improve performance, you can instruct the NodeTraverser to skip parts of the tree or stop entirely by returning specific constants from enterNode():

• NodeVisitor::DONT_TRAVERSE_CHILDREN: Skips the children of the current node. Useful when you know no nested structures of interest exist (e.g., skipping children of a Class_ node if you only want top-level classes).
• NodeVisitor::STOP_TRAVERSAL: Aborts the entire traversal immediately. Useful when you only need to find a single specific node.

public function enterNode(Node $node) {
    if ($node instanceof Node\Stmt\Class_) {
        // Found a class, don't bother looking at its contents
        return NodeVisitor::DONT_TRAVERSE_CHILDREN;
    }
    if ($node instanceof Node\Stmt\Class_ && $node->name === 'TargetClass') {
        // Found exactly what we wanted, stop everything
        return NodeVisitor::STOP_TRAVERSAL;
    }
}