PHP Parser

https://github.com/nikic/php-parser
Admin
PHP Parser is a PHP library that parses PHP code into an abstract syntax tree (AST) to simplify...
Tokens:166,268
Snippets:1,184
Trust Score:9.6
License:BSD-3-Clause
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Fluent builder example using BuilderFactory

Source: https://github.com/nikic/php-parser/blob/master/doc/component/AST_builders.markdown

Shows how to use BuilderFactory to construct a namespace with use statements, a class with traits, methods, and properties, then pretty-print the result. The example includes comments showing alternative modifiers and demonstrates adding manually created nodes.

```php
use PhpParser\BuilderFactory;
use PhpParser\PrettyPrinter;
use PhpParser\Node;

$factory = new BuilderFactory;
$node = $factory->namespace('Name\Space')
    ->addStmt($factory->use('Some\Other\Thingy')->as('SomeClass'))
    ->addStmt($factory->useFunction('strlen'))
    ->addStmt($factory->useConst('PHP_VERSION'))
    ->addStmt($factory->class('SomeOtherClass')
        ->extend('SomeClass')
        ->implement('A\Few', '\Interfaces')
        ->makeAbstract() // ->makeFinal()

        ->addStmt($factory->useTrait('FirstTrait'))

        ->addStmt($factory->useTrait('SecondTrait', 'ThirdTrait')
            ->and('AnotherTrait')
            ->with($factory->traitUseAdaptation('foo')->as('bar'))
            ->with($factory->traitUseAdaptation('AnotherTrait', 'baz')->as('test'))
            ->with($factory->traitUseAdaptation('AnotherTrait', 'func')->insteadof('SecondTrait')))

        ->addStmt($factory->method('someMethod')
            ->makePublic()
            ->makeAbstract() // ->makeFinal()
            ->setReturnType('bool') // ->makeReturnByRef()
            ->addParam($factory->param('someParam')->setType('SomeClass'))
            ->setDocComment('/**
                              * This method does something.
                              *
                              * @param SomeClass And takes a parameter
                              */')
        )

        ->addStmt($factory->method('anotherMethod')
            ->makeProtected() // ->makePublic() [default], ->makePrivate()
            ->addParam($factory->param('someParam')->setDefault('test'))
            // it is possible to add manually created nodes
            ->addStmt(new Node\Expr\Print_(new Node\Expr\Variable('someParam')))
        )

        // properties will be correctly reordered above the methods
        ->addStmt($factory->property('someProperty')->makeProtected())
        ->addStmt($factory->property('anotherProperty')->makePrivate()->setDefault(array(1, 2, 3)))
    )

    ->getNode()
;

$stmts = array($node);
$prettyPrinter = new PrettyPrinter\Standard();
echo $prettyPrinter->prettyPrintFile($stmts);
```

```php
<?php

namespace Name\Space;

use Some\Other\Thingy as SomeClass;
use function strlen;
use const PHP_VERSION;
abstract class SomeOtherClass extends SomeClass implements A\Few, \Interfaces
{
    use FirstTrait;
    use SecondTrait, ThirdTrait, AnotherTrait {
        foo as bar;
        AnotherTrait::baz as test;
        AnotherTrait::func insteadof SecondTrait;
    }
    protected $someProperty;
    private $anotherProperty = [1, 2, 3];
    /**
     * This method does something.
     *
     * @param SomeClass And takes a parameter
     */
    abstract public function someMethod(SomeClass $someParam): bool;
    protected function anotherMethod($someParam = 'test')
    {
        print $someParam;
    }
}
```

--------------------------------

### Install PHP Parser via Composer

Source: https://github.com/nikic/php-parser/blob/master/README.md

Install the library using Composer with the command `php composer.phar require nikic/php-parser`.

```bash
php composer.phar require nikic/php-parser
```

--------------------------------

### Formatting-preserving pretty printing setup before and after

Source: https://github.com/nikic/php-parser/blob/master/UPGRADE-5.0.md

Compares the old lexer configuration and parser setup with the new simplified approach using ParserFactory. The lexer no longer accepts an options array and usedAttributes is removed.

```php
# Before

$lexer = new Lexer\Emulative([
    'usedAttributes' => [
        'comments',
        'startLine', 'endLine',
        'startTokenPos', 'endTokenPos',
    ],
]);

$parser = new Parser\Php7($lexer);
$oldStmts = $parser->parse($code);
$oldTokens = $lexer->getTokens();

$traverser = new NodeTraverser();
$traverser->addVisitor(new NodeVisitor\CloningVisitor());
$newStmts = $traverser->traverse($oldStmts);

# After

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

$traverser = new NodeTraverser(new NodeVisitor\CloningVisitor());
$newStmts = $traverser->traverse($oldStmts);
```

--------------------------------

### Format-preserving pretty printing setup in PHP

Source: https://github.com/nikic/php-parser/blob/master/doc/component/Pretty_printing.markdown

Shows the required steps to use format-preserving pretty printing: parse code, get tokens, clone the AST with CloningVisitor, modify the new statements, and print with PrettyPrinter\Standard::printFormatPreserving. The CloningVisitor must be run before making changes to the AST. If using name resolution, consider disabling the replaceNodes option to avoid spurious changes.

```php
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);
```

--------------------------------

### Order of enter/leave calls for example AST

Source: https://github.com/nikic/php-parser/blob/master/doc/component/Walking_the_AST.markdown

Shows the order in which enterNode and leaveNode are called for the example AST.

```text
enterNode(Expr_FuncCall)
enterNode(Name)
leaveNode(Name)
enterNode(Arg)
enterNode(Scalar_String)
leaveNode(Scalar_String)
leaveNode(Arg)
leaveNode(Expr_FuncCall)
```

--------------------------------

### Example AST excerpt

Source: https://github.com/nikic/php-parser/blob/master/doc/component/Walking_the_AST.markdown

Shows a sample AST structure for a function call with a string argument.

```text
Expr_FuncCall(
   name: Name(
       name: printLine
   )
   args: array(
       0: Arg(
           name: null
           value: Scalar_String(
               value: Hello World!!!
           )
           byRef: false
           unpack: false
       )
   )
)
```

--------------------------------

### Operator pretty-printer implementations

Source: https://github.com/nikic/php-parser/blob/master/UPGRADE-5.0.md

Example implementations for binary and unary operators showing how to pass precedence arguments to pInfixOp and pPrefixOp.

```php
protected function pExpr_BinaryOp_Plus(
    BinaryOp\Plus $node, int $precedence, int $lhsPrecedence
): string {
    return $this->pInfixOp(
        BinaryOp\Plus::class, $node->left, ' + ', $node->right, $precedence, $lhsPrecedence);
}

protected function pExpr_UnaryPlus(
    Expr\UnaryPlus $node, int $precedence, int $lhsPrecedence
): string {
    return $this->pPrefixOp(Expr\UnaryPlus::class, '+', $node->expr, $precedence, $lhsPrecedence);
}

```

--------------------------------

### Example JSON output of encoded AST

Source: https://github.com/nikic/php-parser/blob/master/doc/component/JSON_representation.markdown

Shows the JSON structure produced by the previous example, including attributes like startLine, comments, and node types.

```json
[
    {
        "nodeType": "Stmt_Function",
        "attributes": {
            "startLine": 4,
            "comments": [
                {
                    "nodeType": "Comment_Doc",
                    "text": "\/** @param string $msg *\/",
                    "line": 3,
                    "filePos": 7,
                    "tokenPos": 2,
                    "endLine": 3,
                    "endFilePos": 31,
                    "endTokenPos": 2
                }
            ],
            "endLine": 6
        },
        "byRef": false,
        "name": {
            "nodeType": "Identifier",
            "attributes": {
                "startLine": 4,
                "endLine": 4
            },
            "name": "printLine"
        },
        "params": [
            {
                "nodeType": "Param",
                "attributes": {
                    "startLine": 4,
                    "endLine": 4
                },
                "type": null,
                "byRef": false,
                "variadic": false,
                "var": {
                    "nodeType": "Expr_Variable",
                    "attributes": {
                        "startLine": 4,
                        "endLine": 4
                    },
                    "name": "msg"
                },
                "default": null,
                "flags": 0,
                "attrGroups": []
            }
        ],
        "returnType": null,
        "stmts": [
            {
                "nodeType": "Stmt_Echo",
                "attributes": {
                    "startLine": 5,
                    "endLine": 5
                },
                "exprs": [
                    {
                        "nodeType": "Expr_Variable",
                        "attributes": {
                            "startLine": 5,
                            "endLine": 5
                        },
                        "name": "msg"
                    },
                    {
                        "nodeType": "Scalar_String",
                        "attributes": {
                            "startLine": 5,
                            "endLine": 5,
                            "kind": 2,
                            "rawValue": "\"\\n\""
                        },
                        "value": "\n"
                    }
                ]
            }
        ],
        "attrGroups": [],
        "namespacedName": null
    }
]
```

--------------------------------

### Pretty printing example: parse, modify, and print AST

Source: https://github.com/nikic/php-parser/blob/master/doc/2_Usage_of_basic_components.markdown

This example demonstrates the full workflow of parsing PHP code, modifying a node, and pretty printing the result. It uses ParserFactory, PrettyPrinter\Standard, and handles parse errors with Error. The output is 'echo 'Hello ', hi\getTarget();'.

```php
use PhpParser\Error;
use PhpParser\ParserFactory;
use PhpParser\PrettyPrinter;

$code = "<?php echo 'Hi ', hi\\getTarget();";

$parser = (new ParserFactory())->createForHostVersion();
$prettyPrinter = new PrettyPrinter\Standard();

try {
    // parse
    $stmts = $parser->parse($code);

    // change
    $stmts[0]         // the echo statement
          ->exprs     // sub expressions
          [0]         // the first of them (the string node)
          ->value     // it's value, i.e. 'Hi '
          = 'Hello '; // change to 'Hello '

    // pretty print
    $code = $prettyPrinter->prettyPrint($stmts);

    echo $code;
} catch (Error $e) {
    echo 'Parse Error: ', $e->getMessage(), "\n";
}
```

```php
echo 'Hello ', hi\getTarget();
```

--------------------------------

### Migrating ParserFactory usage to new version-specific methods

Source: https://github.com/nikic/php-parser/blob/master/UPGRADE-5.0.md

Shows how to replace the removed ParserFactory::create() method with the new createForNewestSupportedVersion(), createForHostVersion(), and createForVersion() methods. The example demonstrates the before and after usage for both PREFER_PHP7 and ONLY_PHP5 options.

```php
use PhpParser\ParserFactory;
use PhpParser\PhpVersion;

$factory = new ParserFactory();

# Before
$parser = $factory->create(ParserFactory::PREFER_PHP7);

# After (this is roughly equivalent to PREFER_PHP7 behavior)
$parser = $factory->createForNewestSupportedVersion();
# Or
$parser = $factory->createForHostVersion();

# Before
$parser = $factory->create(ParserFactory::ONLY_PHP5);
# After (supported on a best-effort basis)
$parser = $factory->createForVersion(PhpVersion::fromString("5.6"));
```

--------------------------------

### NameResolver Example with Namespaced Code

Source: https://github.com/nikic/php-parser/blob/master/doc/2_Usage_of_basic_components.markdown

A short code example showing namespaced code that the NameResolver visitor can resolve. The code uses an alias and a namespaced class instantiation.

```php
use A as B;
new B\C();
```

--------------------------------

### Constant expression example with class constants

Source: https://github.com/nikic/php-parser/blob/master/doc/component/Constant_expression_evaluation.markdown

Shows a PHP class with constant initializers using arithmetic and references to other constants, demonstrating the kind of expressions that can be evaluated.

```php
<?php
class Test {
    const SECONDS_IN_HOUR = 60 * 60;
    const SECONDS_IN_DAY = 24 * self::SECONDS_IN_HOUR;
}
```

--------------------------------

### Pretty-print AST back to PHP code

Source: https://github.com/nikic/php-parser/blob/master/README.md

This example uses PrettyPrinter\Standard to convert the modified AST back to PHP code and prints it.

```php
use PhpParser\PrettyPrinter;

$prettyPrinter = new PrettyPrinter\Standard;
echo $prettyPrinter->prettyPrintFile($ast);
```

--------------------------------

### Custom NodeVisitor Example

Source: https://github.com/nikic/php-parser/blob/master/doc/2_Usage_of_basic_components.markdown

A visitor that changes all string literals to 'foo' by overriding leaveNode. Extends NodeVisitorAbstract for default implementations.

```php
use PhpParser\Node;
use PhpParser\NodeVisitorAbstract;

class MyNodeVisitor extends NodeVisitorAbstract {
    public function leaveNode(Node $node) {
        if ($node instanceof Node\Scalar\String_) {
            $node->value = 'foo';
        }
    }
}
```

--------------------------------

### Parse PHP code into an AST and dump it

Source: https://github.com/nikic/php-parser/blob/master/README.md

This example creates a parser for the newest supported PHP version, parses a sample PHP code string, and dumps the resulting AST using NodeDumper. It catches parse errors and prints them.

```php
<?php
use PhpParser\Error;
use PhpParser\NodeDumper;
use PhpParser\ParserFactory;

$code = <<<'CODE'
<?php

function test($foo)
{
    var_dump($foo);
}
CODE;

$parser = (new ParserFactory())->createForNewestSupportedVersion();
try {
    $ast = $parser->parse($code);
} catch (Error $error) {
    echo "Parse error: {$error->getMessage()}\n";
    return;
}

$dumper = new NodeDumper;
echo $dumper->dump($ast) . "\n";
```

--------------------------------

### Node visitor using token positions

Source: https://github.com/nikic/php-parser/blob/master/doc/component/Lexer.markdown

This example shows a node visitor that uses the `isDeclaredUsingVar` function to check each property node. It also demonstrates how to set the tokens on the visitor and traverse the AST, catching parse errors.

```php
class MyNodeVisitor extends PhpParser\NodeVisitorAbstract {
    private $tokens;
    public function setTokens(array $tokens) {
        $this->tokens = $tokens;
    }

    public function leaveNode(PhpParser\Node $node) {
        if ($node instanceof PhpParser\Node\Stmt\Property) {
            var_dump(isDeclaredUsingVar($this->tokens, $node));
        }
    }
}

$parser = (new PhpParser\ParserFactory())->createForHostVersion($lexerOptions);

$visitor = new MyNodeVisitor();
$traverser = new PhpParser\NodeTraverser($visitor);

try {
    $stmts = $parser->parse($code);
    $visitor->setTokens($parser->getTokens());
    $stmts = $traverser->traverse($stmts);
} catch (PhpParser\Error $e) {
    echo 'Parse Error: ', $e->getMessage();
}
```

--------------------------------

### Dump AST with NodeDumper

Source: https://github.com/nikic/php-parser/blob/master/doc/2_Usage_of_basic_components.markdown

Use NodeDumper to dump the abstract syntax tree in human-readable form. The output for the sample code from the parsing example is shown in the following block.

```php
<?php
use PhpParser\NodeDumper;

$nodeDumper = new NodeDumper;
echo $nodeDumper->dump($stmts), "\n";
```

--------------------------------

### NameResolver Visitor Usage

Source: https://github.com/nikic/php-parser/blob/master/doc/component/Name_resolution.markdown

Example of applying the NameResolver visitor to an AST to resolve names to fully-qualified form.

```APIDOC
## NameResolver Visitor Usage

### Description
Applies the NameResolver visitor to an AST to resolve names to fully-qualified form.

### Code Example
```php
$nameResolver = new PhpParser\NodeVisitor\NameResolver;
$nodeTraverser = new PhpParser\NodeTraverser;
$nodeTraverser->addVisitor($nameResolver);

// Resolve names
$stmts = $nodeTraverser->traverse($stmts);
```
```

--------------------------------

### NodeFinder examples for finding AST nodes

Source: https://github.com/nikic/php-parser/blob/master/doc/component/Walking_the_AST.markdown

Demonstrates using NodeFinder to find class nodes, classes that extend another class, the first class, and the first class with a specific name. Requires the use of PhpParser\{Node, NodeFinder}.

```php
use PhpParser\{Node, NodeFinder};

$nodeFinder = new NodeFinder;

// Find all class nodes.
$classes = $nodeFinder->findInstanceOf($stmts, Node\Stmt\Class_::class);

// Find all classes that extend another class
$extendingClasses = $nodeFinder->find($stmts, function(Node $node) {
    return $node instanceof Node\Stmt\Class_
        && $node->extends !== null;
});

// Find first class occurring in the AST. Returns null if no class exists.
$class = $nodeFinder->findFirstInstanceOf($stmts, Node\Stmt\Class_::class);

// Find first class that has name $name
$class = $nodeFinder->findFirst($stmts, function(Node $node) use ($name) {
    return $node instanceof Node\Stmt\Class_
        && $node->resolvedName->toString() === $name;
});
```

--------------------------------

### Infinite recursion example with circular constant references

Source: https://github.com/nikic/php-parser/blob/master/doc/component/Constant_expression_evaluation.markdown

Shows a class with constants referencing each other, which could cause infinite recursion if constant lookup is implemented naively.

```php
<?php
class Test {
    const A = self::B;
    const B = self::A;
}
```

--------------------------------

### Traverse AST and remove function bodies

Source: https://github.com/nikic/php-parser/blob/master/README.md

This example uses NodeTraverser and a custom NodeVisitor to clear the `stmts` property of every Function_ node, effectively removing function bodies.

```php
use PhpParser\Node;
use PhpParser\Node\Stmt\Function_;
use PhpParser\NodeTraverser;
use PhpParser\NodeVisitorAbstract;

$traverser = new NodeTraverser();
$traverser->addVisitor(new class extends NodeVisitorAbstract {
    public function enterNode(Node $node) {
        if ($node instanceof Function_) {
            // Clean out the function body
            $node->stmts = [];
        }
    }
});

$ast = $traverser->traverse($ast);
echo $dumper->dump($ast) . "\n";
```

--------------------------------

### Block representation AST before and after

Source: https://github.com/nikic/php-parser/blob/master/UPGRADE-5.0.md

Shows the AST change for nested code blocks. Before, inner blocks were flattened; after, they are represented with Stmt_Block. The code example is `while ($x) { $a; { $b; } $c; }`.

```php
# Code
while ($x) { $a; { $b; } $c; }

# Before
Stmt_While(
    cond: Expr_Variable(
        name: x
    )
    stmts: array(
        0: Stmt_Expression(
            expr: Expr_Variable(
                name: a
            )
        )
        1: Stmt_Expression(
            expr: Expr_Variable(
                name: b
            )
        )
        2: Stmt_Expression(
            expr: Expr_Variable(
                name: c
            )
        )
    )
)

# After
Stmt_While(
    cond: Expr_Variable(
        name: x
    )
    stmts: array(
        0: Stmt_Expression(
            expr: Expr_Variable(
                name: a
            )
        )
        1: Stmt_Block(
            stmts: array(
                0: Stmt_Expression(
                    expr: Expr_Variable(
                        name: b
                    )
                )
            )
        )
        2: Stmt_Expression(
            expr: Expr_Variable(
                name: c
            )
        )
    )
)
```

--------------------------------

### Example AST output for echo statement

Source: https://github.com/nikic/php-parser/blob/master/doc/0_Introduction.markdown

Shows the node tree produced by parsing the PHP program `<?php echo 'Hi', 'World';`. The AST represents an echo statement with two string expressions, demonstrating the abstract structure without whitespace information.

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

--------------------------------

### Comment assignment AST before and after

Source: https://github.com/nikic/php-parser/blob/master/UPGRADE-5.0.md

Shows the change in comment assignment. Before, comments were attached to all nodes at the same position; after, only to the outermost node. The code example is `// Comment
$a + $b;`.

```php
# Code
// Comment
$a + $b;

# Before
Stmt_Expression(
    expr: Expr_BinaryOp_Plus(
        left: Expr_Variable(
            name: a
            comments: array(
                0: // Comment
            )
        )
        right: Expr_Variable(
            name: b
        )
        comments: array(
            0: // Comment
        )
    )
    comments: array(
        0: // Comment
    )
)

# After
Stmt_Expression(
    expr: Expr_BinaryOp_Plus(
        left: Expr_Variable(
            name: a
        )
        right: Expr_Variable(
            name: b
        )
    )
    comments: array(
        0: // Comment
    )
)
```

--------------------------------

### New throw statement representation

Source: https://github.com/nikic/php-parser/blob/master/UPGRADE-5.0.md

Shows the change in AST representation for throw statements. Previously, a throw statement was represented as Stmt\Throw_, now it is represented as Stmt\Expression containing Expr\Throw_. The example shows the code and the before/after AST structures.

```php
# Code
throw $e;

# Before
Stmt_Throw(
    expr: Expr_Variable(
        name: e
    )
)

# After
Stmt_Expression(
    expr: Expr_Throw(
        expr: Expr_Variable(
            name: e
        )
    )
)
```

--------------------------------

### Create Parser Instances for Different PHP Versions

Source: https://github.com/nikic/php-parser/blob/master/doc/2_Usage_of_basic_components.markdown

Shows how to create parser instances for the host version, the newest supported version, or a specific version. The createXYZ() methods optionally accept an array of lexer options.

```php
use PhpParser\ParserFactory;
use PhpParser\PhpVersion;

// Parser for the version you are running on.
$parser = (new ParserFactory())->createForHostVersion();

// Parser for the newest PHP version supported by the PHP-Parser library.
$parser = (new ParserFactory())->createForNewestSupportedVersion();

// Parser for a specific PHP version.
$parser = (new ParserFactory())->createForVersion(PhpVersion::fromString('8.1'));
```

--------------------------------

### Parse, Traverse, and Pretty Print PHP Code

Source: https://github.com/nikic/php-parser/blob/master/doc/2_Usage_of_basic_components.markdown

Shows the basic workflow: create a parser, traverser, and pretty printer, add a custom visitor, then parse, traverse, and pretty print code. The output is echoed, and parse errors are caught and displayed.

```php
use PhpParser\NodeTraverser;
use PhpParser\ParserFactory;
use PhpParser\PrettyPrinter;

$parser        = (new ParserFactory())->createForHostVersion();
$traverser     = new NodeTraverser;
$prettyPrinter = new PrettyPrinter\Standard;

// add your visitor
$traverser->addVisitor(new MyNodeVisitor);

try {
    $code = file_get_contents($fileName);

    // parse
    $stmts = $parser->parse($code);

    // traverse
    $stmts = $traverser->traverse($stmts);

    // pretty print
    $code = $prettyPrinter->prettyPrintFile($stmts);

    echo $code;
} catch (PhpParser\Error $e) {
    echo 'Parse Error: ', $e->getMessage();
}
```

--------------------------------

### Old parser instantiation (PHP-Parser 1.x)

Source: https://github.com/nikic/php-parser/blob/master/UPGRADE-2.0.md

Shows the old way of creating a parser instance directly with the Parser and Lexer classes, which no longer works in 2.0.

```php
use PhpParser\Parser, PhpParser\Lexer;
$parser = new Parser(new Lexer\Emulative);
```

--------------------------------

### Array destructuring AST before and after

Source: https://github.com/nikic/php-parser/blob/master/UPGRADE-5.0.md

Shows the AST representation change for `[$x] = $y`. Before, it used Expr_Array; after, it uses Expr_List with a kind attribute. The code example is `[$x] = $y;`.

```php
# Code
[$x] = $y;

# Before
Expr_Assign(
   var: Expr_Array(
       items: array(
           0: Expr_ArrayItem(
               key: null
               value: Expr_Variable(
                   name: x
               )
               byRef: false
               unpack: false
           )
       )
   )
   expr: Expr_Variable(
       name: y
   )
)

# After
Expr_Assign(
   var: Expr_List(
       items: array(
           0: ArrayItem(
               key: null
               value: Expr_Variable(
                   name: x
               )
               byRef: false
               unpack: false
           )
       )
   )
   expr: Expr_Variable(
       name: y
   )
)
```

--------------------------------

### New parser instantiation with ParserFactory (PHP-Parser 2.0)

Source: https://github.com/nikic/php-parser/blob/master/UPGRADE-2.0.md

Creates a parser instance using the ParserFactory with PREFER_PHP7 mode, which tries PHP 7 first and falls back to PHP 5.

```php
use PhpParser\ParserFactory;
$parser = (new ParserFactory)->create(ParserFactory::PREFER_PHP7);
```

--------------------------------

### NodeVisitor Interface Methods

Source: https://github.com/nikic/php-parser/blob/master/doc/2_Usage_of_basic_components.markdown

The four methods that all visitors must implement. beforeTraverse and afterTraverse are called once before and after traversal, while enterNode and leaveNode are called on every node.

```php
public function beforeTraverse(array $nodes);
public function enterNode(\PhpParser\Node $node);
public function leaveNode(\PhpParser\Node $node);
public function afterTraverse(array $nodes);
```

--------------------------------

### Main script: parse, traverse, and pretty-print PHP files

Source: https://github.com/nikic/php-parser/blob/master/doc/2_Usage_of_basic_components.markdown

This script iterates over all .php files in a directory, parses each file, traverses with a NameResolver and a custom NamespaceConverter, pretty-prints the result, and writes it to an output directory. It catches PhpParser\Error exceptions and prints parse errors.

```php
use PhpParser\ParserFactory;
use PhpParser\PrettyPrinter;
use PhpParser\NodeTraverser;
use PhpParser\NodeVisitor\NameResolver;

$inDir  = '/some/path';
$outDir = '/some/other/path';

$parser        = (new ParserFactory())->createForNewestSupportedVersion();
$traverser     = new NodeTraverser;
$prettyPrinter = new PrettyPrinter\Standard;

$traverser->addVisitor(new NameResolver); // we will need resolved names
$traverser->addVisitor(new NamespaceConverter); // our own node visitor

// iterate over all .php files in the directory
$files = new \RecursiveIteratorIterator(new \RecursiveDirectoryIterator($inDir));
$files = new \RegexIterator($files, '/\.php$/');

foreach ($files as $file) {
    try {
        // read the file that should be converted
        $code = file_get_contents($file->getPathName());

        // parse
        $stmts = $parser->parse($code);

        // traverse
        $stmts = $traverser->traverse($stmts);

        // pretty print
        $code = $prettyPrinter->prettyPrintFile($stmts);

        // write the converted file to the target directory
        file_put_contents(
            substr_replace($file->getPathname(), $outDir, 0, strlen($inDir)),
            $code
        );
    } catch (PhpParser\Error $e) {
        echo 'Parse Error: ', $e->getMessage();
    }
}
```

--------------------------------

### Run PHP-CS-Fixer and PHPStan with make

Source: https://github.com/nikic/php-parser/blob/master/CONTRIBUTING.md

Use these make commands to run the code style fixer and static analysis tool. They are invoked from the project root.

```shell
make php-cs-fixer
make phpstan
```

--------------------------------

### Check if property declared using var

Source: https://github.com/nikic/php-parser/blob/master/doc/component/Lexer.markdown

This function checks the token at the property's start position to see if it is `T_VAR`, indicating the property was declared with `var` instead of `public`. It requires an array of tokens from the lexer.

```php
/** @param PhpParser\Token[] $tokens */
function isDeclaredUsingVar(array $tokens, PhpParser\Node\Stmt\Property $prop) {
    $i = $prop->getStartTokenPos();
    return $tokens[$i]->id === T_VAR;
}
```

--------------------------------

### NameResolver Constructor Options

Source: https://github.com/nikic/php-parser/blob/master/doc/component/Name_resolution.markdown

Shows how to instantiate NameResolver with an options array to control name resolution behavior.

```APIDOC
## NameResolver Constructor Options

### Description
Creates a NameResolver instance with custom options. The options control whether original names are preserved and whether nodes are replaced in-place.

### Constructor
`new PhpParser\NodeVisitor\NameResolver(?ErrorHandler $errorHandler = null, array $options = [])`

### Parameters
- **errorHandler** (ErrorHandler|null) - Optional - Error handler for name resolution errors.
- **options** (array) - Optional - Options array with the following defaults:
  - `preserveOriginalNames` (bool) - Default: `false` - If enabled, the resolved name will have an `originalName` attribute containing the unresolved name.
  - `replaceNodes` (bool) - Default: `true` - If disabled, names are not resolved in-place; instead a `resolvedName` attribute is added to each name.

### Code Example
```php
$nameResolver = new PhpParser\NodeVisitor\NameResolver(null, [
    'preserveOriginalNames' => false,
    'replaceNodes' => true,
]);
```
```

--------------------------------

### Sample AST dump output

Source: https://github.com/nikic/php-parser/blob/master/README.md

This is the output of the NodeDumper for the parsed code, showing the structure of the AST for the function `test`.

```text
array(
    0: Stmt_Function(
        attrGroups: array(
        )
        byRef: false
        name: Identifier(
            name: test
        )
        params: array(
            0: Param(
                attrGroups: array(
                )
                flags: 0
                type: null
                byRef: false
                variadic: false
                var: Expr_Variable(
                    name: foo
                )
                default: null
            )
        )
        returnType: null
        stmts: array(
            0: Stmt_Expression(
                expr: Expr_FuncCall(
                    name: Name(
                        name: var_dump
                    )
                    args: array(
                        0: Arg(
                            name: null
                            value: Expr_Variable(
                                name: foo
                            )
                            byRef: false
                            unpack: false
                        )
                    )
                )
            )
        )
    )
)
```

--------------------------------

### Passing visitors to NodeTraverser constructor

Source: https://github.com/nikic/php-parser/blob/master/UPGRADE-5.0.md

Shows the old way of adding visitors via addVisitor() and the new way of passing them directly to the constructor. The old method is still supported.

```php
# Before (and still supported)
$traverser = new NodeTraverser();
$traverser->addVisitor(new NameResolver());

# After
$traverser = new NodeTraverser(new NameResolver());
```

--------------------------------

### Visitor callback order before and after

Source: https://github.com/nikic/php-parser/blob/master/UPGRADE-5.0.md

Shows the change in leaveNode() call order when multiple visitors are used. Before, leaveNode() was called in the same order as enterNode(); after, it is called in reverse order.

```php
# Before
$visitor1->enterNode($node);
$visitor2->enterNode($node);
$visitor1->leaveNode($node);
$visitor2->leaveNode($node);

# After
$visitor1->enterNode($node);
$visitor2->enterNode($node);
$visitor2->leaveNode($node);
$visitor1->leaveNode($node);
```

--------------------------------

### new($class, array $args = [])

Source: https://github.com/nikic/php-parser/blob/master/doc/component/AST_builders.markdown

Creates a 'new' (object creation) node. Converts `$class` to a `Name` node.

```APIDOC
## new($class, array $args = [])

### Description
Creates a 'new' (object creation) node. Converts `$class` to a `Name` node.

### Parameters
- **$class** (string|Name) - Required - The class name.
- **$args** (array) - Optional - An array of arguments for the constructor.

### Returns
New expression AST node.
```

--------------------------------

### startLexing() signature change

Source: https://github.com/nikic/php-parser/blob/master/UPGRADE-3.0.md

Shows the old and new signatures for the startLexing() method. Custom lexers with overridden startLexing() must accept the extra ErrorHandler parameter and pass it to the parent method.

```php
// OLD
public function startLexing($code);
// NEW
public function startLexing($code, ErrorHandler $errorHandler = null);
```

--------------------------------

### Rebuild parser with php grammar/rebuildParsers.php

Source: https://github.com/nikic/php-parser/blob/master/grammar/README.md

Run this command from the grammar directory to rebuild the parsers. The KMYACC environment variable can override the default phpyacc binary, and the --debug and --keep-tmp-grammar options control debug output and temporary file preservation.

```bash
php grammar/rebuildParsers.php
```

--------------------------------

### propertyFetch($var, $name)

Source: https://github.com/nikic/php-parser/blob/master/doc/component/AST_builders.markdown

Creates a property fetch node. Converts `$name` to an `Identifier` node.

```APIDOC
## propertyFetch($var, $name)

### Description
Creates a property fetch node. Converts `$name` to an `Identifier` node.

### Parameters
- **$var** (Expr) - Required - The expression representing the object.
- **$name** (string|Identifier) - Required - The property name.

### Returns
Property fetch AST node.
```

--------------------------------

### Old namespaced class instantiation (discouraged)

Source: https://github.com/nikic/php-parser/blob/master/UPGRADE-1.0.md

Shows the old underscore-based class names that still work but are discouraged. The PHPParser prefix is case-insensitive but the autoloader will not load case variants.

```php
$parser = new \PHPParser_Parser(new \PHPParser_Lexer_Emulative);
$prettyPrinter = new \PHPParser_PrettyPrinter_Default;
```

--------------------------------

### Basic usage of PhpParser\PrettyPrinter\Standard with prettyPrintFile

Source: https://github.com/nikic/php-parser/blob/master/doc/component/Pretty_printing.markdown

Parses PHP code, allows modification of the statement array, and prints the modified AST as a full PHP file including the opening <?php tag.

```php
$stmts = $parser->parse($code);

// MODIFY $stmts here

$prettyPrinter = new PhpParser\PrettyPrinter\Standard;
$newCode = $prettyPrinter->prettyPrintFile($stmts);
```

--------------------------------

### Multiple NodeTraverser visitors sequentially

Source: https://github.com/nikic/php-parser/blob/master/doc/component/Walking_the_AST.markdown

Shows how to apply multiple visitors by chaining NodeTraverser instances. Note the typo 'traverser' instead of 'traverse' in the method calls.

```php
$traverserA = new NodeTraverser;
$traverserA->addVisitor($visitorA);
$traverserB = new NodeTraverser;
$traverserB->addVisitor($visitorB);
$stmts = $traverserA->traverser($stmts);
$stmts = $traverserB->traverser($stmts);
```

--------------------------------

### Require Composer Autoloader

Source: https://github.com/nikic/php-parser/blob/master/doc/2_Usage_of_basic_components.markdown

Include the Composer-generated autoloader to bootstrap the library.

```php
require 'path/to/vendor/autoload.php';
```

--------------------------------

### Obtain parent and sibling nodes with NodeConnectingVisitor

Source: https://github.com/nikic/php-parser/blob/master/doc/component/FAQ.markdown

Use NodeConnectingVisitor to store parent, previous, and next nodes. After traversal, access them via getAttribute('parent'), getAttribute('previous'), and getAttribute('next'). Do not use with ParentConnectingVisitor simultaneously.

```php
use PhpParser\NodeTraverser;
use PhpParser\NodeVisitor\NodeConnectingVisitor;
use PhpParser\ParserFactory;

$code = '...';

$traverser = new NodeTraverser(new NodeConnectingVisitor);

$parser = (new ParserFactory())->createForHostVersion();
$ast    = $parser->parse($code);
$ast    = $traverser->traverse($ast);
```

--------------------------------

### Error handling: evaluateDirectly vs evaluateSilently

Source: https://github.com/nikic/php-parser/blob/master/doc/component/Constant_expression_evaluation.markdown

Demonstrates the difference between evaluateDirectly and evaluateSilently when evaluating a division by zero. evaluateDirectly returns INF with a warning, while evaluateSilently throws an exception with the error message.

```php
<?php

use PhpParser\{ConstExprEvaluator, ConstExprEvaluationException};
use PhpParser\Node\{Expr, Scalar};

$evaluator = new ConstExprEvaluator();

// 10 / 0
$expr = new Expr\BinaryOp\Div(new Scalar\Int_(10), new Scalar\Int_(0));

var_dump($evaluator->evaluateDirectly($expr)); // float(INF)
// Warning: Division by zero

try {
    $evaluator->evaluateSilently($expr);
} catch (ConstExprEvaluationException $e) {
    var_dump($e->getPrevious()->getMessage()); // Division by zero
}
```

--------------------------------

### classConstFetch($class, $name)

Source: https://github.com/nikic/php-parser/blob/master/doc/component/AST_builders.markdown

Creates a class constant fetch node. Converts `$class` to a `Name` node and `$name` to an `Identifier` node.

```APIDOC
## classConstFetch($class, $name)

### Description
Creates a class constant fetch node. Converts `$class` to a `Name` node and `$name` to an `Identifier` node.

### Parameters
- **$class** (string|Name) - Required - The class name.
- **$name** (string|Identifier) - Required - The constant name.

### Returns
Class constant fetch AST node.
```

--------------------------------

### args(array $args)

Source: https://github.com/nikic/php-parser/blob/master/doc/component/AST_builders.markdown

Creates an array of function/method arguments, including the required `Arg` wrappers. Also converts literals to AST nodes.

```APIDOC
## args(array $args)

### Description
Creates an array of function/method arguments, including the required `Arg` wrappers. Also converts literals to AST nodes.

### Parameters
- **$args** (array) - Required - An array of arguments to be wrapped.

### Returns
Array of `Arg` nodes.
```

--------------------------------

### New namespaced class instantiation

Source: https://github.com/nikic/php-parser/blob/master/UPGRADE-1.0.md

Shows the new namespaced class names with the PhpParser prefix. The PHPParser prefix was changed to PhpParser, and some class names now end with an underscore due to reserved keywords.

```php
$parser = new \PhpParser\Parser(new PhpParser\Lexer\Emulative);
$prettyPrinter = new \PhpParser\PrettyPrinter\Standard;
```

--------------------------------

### staticCall($class, $name, array $args = [])

Source: https://github.com/nikic/php-parser/blob/master/doc/component/AST_builders.markdown

Creates a static method call node. Converts `$class` to a `Name` node, `$name` to an `Identifier` node and normalizes arguments.

```APIDOC
## staticCall($class, $name, array $args = [])

### Description
Creates a static method call node. Converts `$class` to a `Name` node, `$name` to an `Identifier` node and normalizes arguments.

### Parameters
- **$class** (string|Name) - Required - The class name.
- **$name** (string|Identifier) - Required - The static method name.
- **$args** (array) - Optional - An array of arguments for the static method call.

### Returns
Static method call AST node.
```

--------------------------------

### Apply NameResolver visitor to resolve names

Source: https://github.com/nikic/php-parser/blob/master/doc/component/Name_resolution.markdown

Creates a NameResolver visitor and traverses the AST to resolve names to fully-qualified form. This is the default usage and should be applied for nearly all AST uses.

```php
$nameResolver = new PhpParser\NodeVisitor\NameResolver;
$nodeTraverser = new PhpParser\NodeTraverser;
$nodeTraverser->addVisitor($nameResolver);

// Resolve names
$stmts = $nodeTraverser->traverse($stmts);
```

--------------------------------

### var($name)

Source: https://github.com/nikic/php-parser/blob/master/doc/component/AST_builders.markdown

Creates a variable node for the given variable name.

```APIDOC
## var($name)

### Description
Creates a variable node for the given variable name.

### Parameters
- **$name** (string) - Required - The name of the variable.

### Returns
Variable AST node.
```

--------------------------------

### Collect class declarations with NodeVisitor::DONT_TRAVERSE_CHILDREN

Source: https://github.com/nikic/php-parser/blob/master/doc/component/Walking_the_AST.markdown

Collects all class declarations without recursing into their children, improving performance. Only available in enterNode.

```php
private $classes = [];
public function enterNode(Node $node) {
    if ($node instanceof Node\Stmt\Class_) {
        $this->classes[] = $node;
        return NodeVisitor::DONT_TRAVERSE_CHILDREN;
    }
}
```

--------------------------------

### methodCall(Expr $var, $name, array $args = [])

Source: https://github.com/nikic/php-parser/blob/master/doc/component/AST_builders.markdown

Creates a method call node. Converts `$name` to an `Identifier` node and normalizes arguments.

```APIDOC
## methodCall(Expr $var, $name, array $args = [])

### Description
Creates a method call node. Converts `$name` to an `Identifier` node and normalizes arguments.

### Parameters
- **$var** (Expr) - Required - The expression representing the object on which the method is called.
- **$name** (string|Identifier) - Required - The method name.
- **$args** (array) - Optional - An array of arguments for the method call.

### Returns
Method call AST node.
```

--------------------------------

### funcCall($name, array $args = [])

Source: https://github.com/nikic/php-parser/blob/master/doc/component/AST_builders.markdown

Creates a function call node. Converts `$name` to a `Name` node and normalizes arguments.

```APIDOC
## funcCall($name, array $args = [])

### Description
Creates a function call node. Converts `$name` to a `Name` node and normalizes arguments.

### Parameters
- **$name** (string|Name) - Required - The function name.
- **$args** (array) - Optional - An array of arguments for the function call.

### Returns
Function call AST node.
```

--------------------------------

### attribute($name, $args)

Source: https://github.com/nikic/php-parser/blob/master/doc/component/AST_builders.markdown

Creates an `Attribute` node. Converts `$name` to a `Name` node and normalizes arguments.

```APIDOC
## attribute($name, $args)

### Description
Creates an `Attribute` node. Converts `$name` to a `Name` node and normalizes arguments.

### Parameters
- **$name** (string|Name) - Required - The attribute name.
- **$args** (array) - Required - An array of arguments for the attribute.

### Returns
Attribute AST node.
```

--------------------------------

### New p() method signature

Source: https://github.com/nikic/php-parser/blob/master/UPGRADE-5.0.md

The internal p() method now accepts precedence and parent format preserved parameters. This is used for recursive node printing.

```php
protected function p(
    Node $node, int $precedence = self::MAX_PRECEDENCE, int $lhsPrecedence = self::MAX_PRECEDENCE,
    bool $parentFormatPreserved = false
): string;

```

--------------------------------

### Fallback function for unsupported expressions

Source: https://github.com/nikic/php-parser/blob/master/doc/component/Constant_expression_evaluation.markdown

Shows how to provide a fallback function to handle unsupported expression types like ConstFetch and ClassConstFetch. The fallback must throw ConstExprEvaluationException for unhandled types.

```php
<?php

use PhpParser\{ConstExprEvaluator, ConstExprEvaluationException};
use PhpParser\Node\Expr;

$evaluator = new ConstExprEvaluator(function(Expr $expr) {
    if ($expr instanceof Expr\ConstFetch) {
        return fetchConstantSomehow($expr);
    }
    if ($expr instanceof Expr\ClassConstFetch) {
        return fetchClassConstantSomehow($expr);
    }
    // etc.
    throw new ConstExprEvaluationException(
        "Expression of type {$expr->getType()} cannot be evaluated");
});

try {
    $evaluator->evaluateSilently($someExpr);
} catch (ConstExprEvaluationException $e) {
    // Handle exception
}
```

--------------------------------

### Custom lexer with ParserFactory (PHP-Parser 2.0)

Source: https://github.com/nikic/php-parser/blob/master/UPGRADE-2.0.md

Passes a custom lexer as the second argument to the create() method of ParserFactory.

```php
use PhpParser\ParserFactory;
$lexer = new MyLexer;
$parser = (new ParserFactory)->create(ParserFactory::PREFER_PHP7, $lexer);
```

--------------------------------

### Space between use and parenthesis for closures

Source: https://github.com/nikic/php-parser/blob/master/UPGRADE-5.0.md

Shows the before and after of closure use syntax. In PHP-Parser 5.0, a space is printed between use and the following parenthesis.

```php
# Before
function () use($var) {
};

# After
function () use ($var) {
};

```

--------------------------------

### concat(...$exprs)

Source: https://github.com/nikic/php-parser/blob/master/doc/component/AST_builders.markdown

Creates a tree of `BinaryOp\Concat` nodes for the given expressions.

```APIDOC
## concat(...$exprs)

### Description
Creates a tree of `BinaryOp\Concat` nodes for the given expressions.

### Parameters
- **$exprs** (Expr...) - Required - The expressions to concatenate.

### Returns
BinaryOp\Concat AST node tree.
```

--------------------------------

### AST excerpt showing Stmt_Return with Expr_Variable

Source: https://github.com/nikic/php-parser/blob/master/doc/component/Walking_the_AST.markdown

Shows the AST structure used to illustrate the interleaved visitor call order.

```text
Stmt_Return(
    expr: Expr_Variable(
        name: foobar
    )
)
```

--------------------------------

### constFetch($name)

Source: https://github.com/nikic/php-parser/blob/master/doc/component/AST_builders.markdown

Creates a constant fetch node. Converts `$name` to a `Name` node.

```APIDOC
## constFetch($name)

### Description
Creates a constant fetch node. Converts `$name` to a `Name` node.

### Parameters
- **$name** (string|Name) - Required - The constant name.

### Returns
Constant fetch AST node.
```

--------------------------------

### Use php-parse Script to Dump AST

Source: https://github.com/nikic/php-parser/blob/master/doc/2_Usage_of_basic_components.markdown

The php-parse script can be called with a file name or a code string to obtain a node dump. This is helpful for quickly checking how syntax is represented in the AST.

```sh
vendor/bin/php-parse file.php
vendor/bin/php-parse "<?php foo();"
```
Tokens:
Raw