Release PHP-Parser 5.0.0rc1

Fixes #967.

.editorconfig

@@ -0,0 +1,9 @@
+root = true
+
+[*.y]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 4

.gitattributes

@@ -0,0 +1,13 @@
+/.github         export-ignore
+/doc             export-ignore
+/grammar         export-ignore
+/test            export-ignore
+/test_old        export-ignore
+/tools           export-ignore
+.editorconfig    export-ignore
+.gitattributes   export-ignore
+.gitignore       export-ignore
+CHANGELOG.md     export-ignore
+CONTRIBUTING.md  export-ignore
+phpunit.xml.dist export-ignore
+UPGRADE-*.md     export-ignore

.github/workflows/main.yml

@@ -0,0 +1,119 @@
+# https://help.github.com/en/categories/automating-your-workflow-with-github-actions
+name: Main
+on:
+  push:
+  pull_request:
+
+jobs:
+  tests_coverage:
+    runs-on: "ubuntu-latest"
+    name: "PHP 7.4 Unit Tests (with coverage)"
+    steps:
+      - name: "Checkout"
+        uses: "actions/checkout@v3"
+      - name: "Install PHP"
+        uses: "shivammathur/setup-php@v2"
+        with:
+          coverage: "xdebug"
+          php-version: "7.4"
+          tools: composer:v2
+      - name: "Install dependencies"
+        run: |
+          composer require php-coveralls/php-coveralls:^2.2 --dev --no-update
+          composer update --no-progress --prefer-dist
+      - name: "Tests"
+        run: "php vendor/bin/phpunit --coverage-clover build/logs/clover.xml"
+      - name: Coveralls
+        env:
+          COVERALLS_REPO_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: "php vendor/bin/php-coveralls"
+        if: ${{ success() }}
+  tests:
+    runs-on: "ubuntu-latest"
+    name: "PHP ${{ matrix.php-version }} Unit Tests"
+    strategy:
+      matrix:
+        php-version:
+          - "8.0"
+          - "8.1"
+          - "8.2"
+          - "8.3"
+    steps:
+      - name: "Checkout"
+        uses: "actions/checkout@v3"
+      - name: "Install PHP"
+        uses: "shivammathur/setup-php@v2"
+        with:
+          coverage: "none"
+          php-version: "${{ matrix.php-version }}"
+          tools: composer:v2
+      - name: "Install dependencies"
+        run: "composer update --no-progress --prefer-dist ${{ matrix.flags }}"
+      - name: "PHPUnit"
+        run: "php vendor/bin/phpunit"
+  test_old_73_80:
+    runs-on: "ubuntu-latest"
+    name: "PHP 7.4 Code on PHP 8.2 Integration Tests"
+    steps:
+      - name: "Checkout"
+        uses: "actions/checkout@v3"
+      - name: "Install PHP"
+        uses: "shivammathur/setup-php@v2"
+        with:
+          coverage: "none"
+          php-version: "8.2"
+          tools: composer:v2
+      - name: "Install PHP 8 dependencies"
+        run: "composer update --no-progress --prefer-dist"
+      - name: "Tests"
+        run: "test_old/run-php-src.sh 7.4.33"
+  test_old_80_70:
+    runs-on: "ubuntu-latest"
+    name: "PHP 8.3 Code on PHP 7.4 Integration Tests"
+    steps:
+      - name: "Checkout"
+        uses: "actions/checkout@v3"
+      - name: "Install PHP"
+        uses: "shivammathur/setup-php@v2"
+        with:
+          coverage: "none"
+          php-version: "7.4"
+          tools: composer:v2
+      - name: "Install PHP 8 dependencies"
+        run: "composer update --no-progress --prefer-dist"
+      - name: "Tests"
+        run: "test_old/run-php-src.sh 8.3.0RC2"
+  phpstan:
+    runs-on: "ubuntu-latest"
+    name: "PHPStan"
+    steps:
+      - name: "Checkout"
+        uses: "actions/checkout@v3"
+      - name: "Install PHP"
+        uses: "shivammathur/setup-php@v2"
+        with:
+          coverage: "none"
+          php-version: "8.2"
+          tools: composer:v2
+      - name: "Install dependencies"
+        run: |
+          cd tools && composer install
+      - name: "PHPStan"
+        run: "php tools/vendor/bin/phpstan"
+  php-cs-fixer:
+    runs-on: "ubuntu-latest"
+    name: "PHP-CS-Fixer"
+    steps:
+      - name: "Checkout"
+        uses: "actions/checkout@v3"
+      - name: "Install PHP"
+        uses: "shivammathur/setup-php@v2"
+        with:
+          coverage: "none"
+          php-version: "8.2"
+          tools: composer:v2
+      - name: "Install dependencies"
+        run: |
+          cd tools && composer install
+      - name: "php-cs-fixer"
+        run: "php tools/vendor/bin/php-cs-fixer fix --dry-run"

.gitignore

@@ -0,0 +1,7 @@
+.idea/
+vendor/
+composer.lock
+grammar/kmyacc.exe
+grammar/y.output
+.phpunit.result.cache
+.php-cs-fixer.cache

.php-cs-fixer.dist.php

@@ -0,0 +1,31 @@
+<?php
+
+$finder = PhpCsFixer\Finder::create()
+    ->exclude('PhpParser/Parser')
+    ->in(__DIR__ . '/lib')
+    ->in(__DIR__ . '/test')
+    ->in(__DIR__ . '/grammar')
+;
+
+$config = new PhpCsFixer\Config();
+return $config->setRiskyAllowed(true)
+    ->setRules([
+        '@PSR12' => true,
+        // We use PSR12 with consistent brace placement.
+        'curly_braces_position' => [
+            'functions_opening_brace' => 'same_line',
+            'classes_opening_brace' => 'same_line',
+        ],
+        // declare(strict_types=1) on the same line as <?php.
+        'blank_line_after_opening_tag' => false,
+        'declare_strict_types' => true,
+        // Keep argument formatting for now.
+        'method_argument_space' => ['on_multiline' => 'ignore'],
+        'phpdoc_align' => ['align' => 'left'],
+        'phpdoc_trim' => true,
+        'no_empty_phpdoc' => true,
+        'no_superfluous_phpdoc_tags' => ['allow_mixed' => true],
+        'no_extra_blank_lines' => true,
+    ])
+    ->setFinder($finder)
+;

.travis.yml

@@ -1,14 +0,0 @@
-language: php
-
-php:
-  - 5.3
-  - 5.4
-  - 5.5
-  - 5.6
-  - 7.0
-  - hhvm
-
-matrix:
-  allow_failures:
-    - php: 7.0
-  fast_finish: true

CONTRIBUTING.md

@@ -0,0 +1,4 @@
+## Coding Style
+
+This project uses PSR-12 with consistent brace placement. This means that the opening brace is
+always on the same line, even for class and method declarations.

LICENSE

@@ -1,31 +1,29 @@
-Copyright (c) 2011 by Nikita Popov.
+BSD 3-Clause License
 
-Some rights reserved.
+Copyright (c) 2011, Nikita Popov
+All rights reserved.
 
 Redistribution and use in source and binary forms, with or without
-modification, are permitted provided that the following conditions are
-met:
+modification, are permitted provided that the following conditions are met:
 
-    * Redistributions of source code must retain the above copyright
-      notice, this list of conditions and the following disclaimer.
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
 
-    * Redistributions in binary form must reproduce the above
-      copyright notice, this list of conditions and the following
-      disclaimer in the documentation and/or other materials provided
-      with the distribution.
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
 
-    * The names of the contributors may not be used to endorse or
-      promote products derived from this software without specific
-      prior written permission.
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
 
-THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
-"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
-LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
-A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
-OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
-SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
-LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
-DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
-THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
-(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
-OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Makefile

@@ -0,0 +1,10 @@
+.PHONY: phpstan php-cs-fixer
+
+tools/vendor:
+	composer install -d tools
+
+phpstan: tools/vendor
+	tools/vendor/bin/phpstan
+
+php-cs-fixer: tools/vendor
+	tools/vendor/bin/php-cs-fixer fix

README.md

@@ -1,87 +1,235 @@
 PHP Parser
 ==========
 
-This is a PHP 5.2 to PHP 5.6 parser written in PHP. Its purpose is to simplify static code analysis and
+[![Coverage Status](https://coveralls.io/repos/github/nikic/PHP-Parser/badge.svg?branch=master)](https://coveralls.io/github/nikic/PHP-Parser?branch=master)
+
+This is a PHP parser written in PHP. Its purpose is to simplify static code analysis and
 manipulation.
 
-[**Documentation for version 1.x**][doc_1_x] (stable; for running on PHP >= 5.3).
+[Documentation for version 5.x][doc_master] (in development; for running on PHP >= 7.4; for parsing PHP 7.0 to PHP 8.3, with limited support for parsing PHP 5.x).
 
-[Documentation for version 0.9.x][doc_0_9] (unsupported; for running on PHP 5.2).
+[**Documentation for version 4.x**][doc_4_x] (stable; for running on PHP >= 7.0; for parsing PHP 5.2 to PHP 8.3).
 
-In a Nutshell
--------------
+[Documentation for version 3.x][doc_3_x] (unsupported; for running on PHP >= 5.5; for parsing PHP 5.2 to PHP 7.2).
 
-The parser turns PHP source code into an abstract syntax tree. For example, if you pass the following code into the
-parser:
+Features
+--------
+
+The main features provided by this library are:
+
+ * Parsing PHP 7, and PHP 8 code into an abstract syntax tree (AST).
+   * Invalid code can be parsed into a partial AST.
+   * The AST contains accurate location information.
+ * Dumping the AST in human-readable form.
+ * Converting an AST back to PHP code.
+   * Formatting can be preserved for partially changed ASTs.
+ * Infrastructure to traverse and modify ASTs.
+ * Resolution of namespaced names.
+ * Evaluation of constant expressions.
+ * Builders to simplify AST construction for code generation.
+ * Converting an AST into JSON and back.
+
+Quick Start
+-----------
+
+Install the library using [composer](https://getcomposer.org):
+
+    php composer.phar require nikic/php-parser
+
+Parse some PHP code into an AST and dump the result in human-readable form:
 
 ```php
 <?php
-echo 'Hi', 'World';
-hello\world('foo', 'bar' . 'baz');
+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";
 ```
 
-You'll get a syntax tree looking roughly like this:
+This dumps an AST looking something like this:
 
-```php
+```
 array(
-    0: Stmt_Echo(
-        exprs: array(
-            0: Scalar_String(
-                value: Hi
-            )
-            1: Scalar_String(
-                value: World
+    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
             )
         )
-    )
-    1: Expr_FuncCall(
-        name: Name(
-            parts: array(
-                0: hello
-                1: world
-            )
-        )
-        args: array(
-            0: Arg(
-                value: Scalar_String(
-                    value: foo
-                )
-                byRef: false
-            )
-            1: Arg(
-                value: Expr_Concat(
-                    left: Scalar_String(
-                        value: bar
+        returnType: null
+        stmts: array(
+            0: Stmt_Expression(
+                expr: Expr_FuncCall(
+                    name: Name(
+                        name: var_dump
                     )
-                    right: Scalar_String(
-                        value: baz
+                    args: array(
+                        0: Arg(
+                            name: null
+                            value: Expr_Variable(
+                                name: foo
+                            )
+                            byRef: false
+                            unpack: false
+                        )
                     )
                 )
-                byRef: false
             )
         )
     )
 )
 ```
 
-You can then work with this syntax tree, for example to statically analyze the code (e.g. to find
-programming errors or security issues).
+Let's traverse the AST and perform some kind of modification. For example, drop all function bodies:
 
-Additionally, you can convert a syntax tree back to PHP code. This allows you to do code preprocessing
-(like automatedly porting code to older PHP versions).
+```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";
+```
+
+This gives us an AST where the `Function_::$stmts` are empty:
+
+```
+array(
+    0: Stmt_Function(
+        attrGroups: array(
+        )
+        byRef: false
+        name: Identifier(
+            name: test
+        )
+        params: array(
+            0: Param(
+                attrGroups: array(
+                )
+                type: null
+                byRef: false
+                variadic: false
+                var: Expr_Variable(
+                    name: foo
+                )
+                default: null
+            )
+        )
+        returnType: null
+        stmts: array(
+        )
+    )
+)
+```
+
+Finally, we can convert the new AST back to PHP code:
+
+```php
+use PhpParser\PrettyPrinter;
+
+$prettyPrinter = new PrettyPrinter\Standard;
+echo $prettyPrinter->prettyPrintFile($ast);
+```
+
+This gives us our original code, minus the `var_dump()` call inside the function:
+
+```php
+<?php
+
+function test($foo)
+{
+}
+```
+
+For a more comprehensive introduction, see the documentation.
 
 Documentation
 -------------
 
  1. [Introduction](doc/0_Introduction.markdown)
- 2. [Installation](doc/1_Installation.markdown)
- 3. [Usage of basic components](doc/2_Usage_of_basic_components.markdown)
- 4. [Other node tree representations](doc/3_Other_node_tree_representations.markdown)
- 5. [Code generation](doc/4_Code_generation.markdown)
+ 2. [Usage of basic components](doc/2_Usage_of_basic_components.markdown)
 
 Component documentation:
 
- 1. [Lexer](doc/component/Lexer.markdown)
+ * [Walking the AST](doc/component/Walking_the_AST.markdown)
+   * Node visitors
+   * Modifying the AST from a visitor
+   * Short-circuiting traversals
+   * Interleaved visitors
+   * Simple node finding API
+   * Parent and sibling references
+ * [Name resolution](doc/component/Name_resolution.markdown)
+   * Name resolver options
+   * Name resolution context
+ * [Pretty printing](doc/component/Pretty_printing.markdown)
+   * Converting AST back to PHP code
+   * Customizing formatting
+   * Formatting-preserving code transformations
+ * [AST builders](doc/component/AST_builders.markdown)
+   * Fluent builders for AST nodes
+ * [Lexer](doc/component/Lexer.markdown)
+   * Emulation
+   * Tokens, positions and attributes
+ * [Error handling](doc/component/Error_handling.markdown)
+   * Column information for errors
+   * Error recovery (parsing of syntactically incorrect code)
+ * [Constant expression evaluation](doc/component/Constant_expression_evaluation.markdown)
+   * Evaluating constant/property/etc initializers
+   * Handling errors and unsupported expressions
+ * [JSON representation](doc/component/JSON_representation.markdown)
+   * JSON encoding and decoding of ASTs
+ * [Performance](doc/component/Performance.markdown)
+   * Disabling Xdebug
+   * Reusing objects
+   * Garbage collection impact
+ * [Frequently asked questions](doc/component/FAQ.markdown)
+   * Parent and sibling references
 
- [doc_0_9]: https://github.com/nikic/PHP-Parser/tree/0.9/doc
- [doc_1_x]: https://github.com/nikic/PHP-Parser/tree/1.x/doc
+ [doc_3_x]: https://github.com/nikic/PHP-Parser/tree/3.x/doc
+ [doc_4_x]: https://github.com/nikic/PHP-Parser/tree/4.x/doc
+ [doc_master]: https://github.com/nikic/PHP-Parser/tree/master/doc

UPGRADE-2.0.md

@@ -0,0 +1,74 @@
+Upgrading from PHP-Parser 1.x to 2.0
+====================================
+
+### PHP version requirements
+
+PHP-Parser now requires PHP 5.4 or newer to run. It is however still possible to *parse* PHP 5.2 and
+PHP 5.3 source code, while running on a newer version.
+
+### Creating a parser instance
+
+Parser instances should now be created through the `ParserFactory`. Old direct instantiation code
+will not work, because the parser class was renamed.
+
+Old:
+
+```php
+use PhpParser\Parser, PhpParser\Lexer;
+$parser = new Parser(new Lexer\Emulative);
+```
+
+New:
+
+```php
+use PhpParser\ParserFactory;
+$parser = (new ParserFactory)->create(ParserFactory::PREFER_PHP7);
+```
+
+The first argument to `ParserFactory` determines how different PHP versions are handled. The
+possible values are:
+
+ * `ParserFactory::PREFER_PHP7`: Try to parse code as PHP 7. If this fails, try to parse it as PHP 5.
+ * `ParserFactory::PREFER_PHP5`: Try to parse code as PHP 5. If this fails, try to parse it as PHP 7.
+ * `ParserFactory::ONLY_PHP7`: Parse code as PHP 7.
+ * `ParserFactory::ONLY_PHP5`: Parse code as PHP 5.
+
+For most practical purposes the difference between `PREFER_PHP7` and `PREFER_PHP5` is mainly whether
+a scalar type hint like `string` will be stored as `'string'` (PHP 7) or as `new Name('string')`
+(PHP 5).
+
+To use a custom lexer, pass it as the second argument to the `create()` method:
+
+```php
+use PhpParser\ParserFactory;
+$lexer = new MyLexer;
+$parser = (new ParserFactory)->create(ParserFactory::PREFER_PHP7, $lexer);
+```
+
+### Rename of the `PhpParser\Parser` class
+
+`PhpParser\Parser` is now an interface, which is implemented by `Parser\Php5`, `Parser\Php7` and
+`Parser\Multiple`. Parser tokens are now defined in `Parser\Tokens`. If you use the `ParserFactory`
+described above to create your parser instance, these changes should have no further impact on you.
+
+### Removal of legacy aliases
+
+All legacy aliases for classes have been removed. This includes the old non-namespaced `PHPParser_`
+classes, as well as the classes that had to be renamed for PHP 7 support.
+
+### Deprecations
+
+The `set()`, `setFirst()`, `append()` and `prepend()` methods of the `Node\Name` class have been
+deprecated. Instead `Name::concat()` and `Name->slice()` should be used.
+
+### Miscellaneous
+
+* The `NodeTraverser` no longer clones nodes by default. If you want to restore the old behavior,
+  pass `true` to the constructor.
+* The legacy node format has been removed. If you use custom nodes, they are now expected to
+  implement a `getSubNodeNames()` method.
+* The default value for `Scalar` node constructors was removed. This means that something like
+  `new LNumber()` should be replaced by `new LNumber(0)`.
+* String parts of encapsed strings are now represented using `Scalar\EncapsStringPart` nodes, while
+  previously raw strings were used. This affects the `parts` child of `Scalar\Encaps` and
+  `Expr\ShellExec`.

UPGRADE-3.0.md

@@ -0,0 +1,160 @@
+Upgrading from PHP-Parser 2.x to 3.0
+====================================
+
+The backwards-incompatible changes in this release may be summarized as follows:
+
+ * The specific details of the node representation have changed in some cases, primarily to
+   accommodate new PHP 7.1 features.
+ * There have been significant changes to the error recovery implementation. This may affect you,
+   if you used the error recovery mode or have a custom lexer implementation.
+ * A number of deprecated methods were removed.
+
+### PHP version requirements
+
+PHP-Parser now requires PHP 5.5 or newer to run. It is however still possible to *parse* PHP 5.2,
+5.3 and 5.4 source code, while running on a newer version.
+
+### Changes to the node structure
+
+The following changes are likely to require code changes if the respective nodes are used:
+
+ * The `List` subnode `vars` has been renamed to `items` and now contains `ArrayItem`s instead of
+   plain variables.
+ * The `Catch` subnode `type` has been renamed to `types` and is now an array of `Name`s.
+ * The `TryCatch` subnode `finallyStmts` has been replaced with a `finally` subnode that holds an
+   explicit `Finally` node.
+ * The `type` subnode on `Class`, `ClassMethod` and `Property` has been renamed to `flags`. The
+   `type` subnode has retained for backwards compatibility and is populated to the same value as
+   `flags`. However, writes to `type` will not update `flags` and use of `type` is discouraged.
+
+The following changes are unlikely to require code changes:
+
+ * The `ClassConst` constructor changed to accept an additional `flags` subnode.
+ * The `Trait` constructor now has the same form as the `Class` and `Interface` constructors: It
+   takes an array of subnodes. Unlike classes/interfaces, traits can only have a `stmts` subnode.
+ * The `Array` subnode `items` may now contain `null` elements (due to destructuring).
+ * `void` and `iterable` types are now stored as strings if the PHP 7 parser is used. Previously
+   these would have been represented as `Name` instances.
+
+### Changes to error recovery mode
+
+Previously, error recovery mode was enabled by setting the `throwOnError` option to `false` when
+creating the parser, while collected errors were retrieved using the `getErrors()` method:
+
+```php
+$lexer = ...;
+$parser = (new ParserFactory)->create(ParserFactor::ONLY_PHP7, $lexer, [
+    'throwOnError' => true,
+]);
+
+$stmts = $parser->parse($code);
+$errors = $parser->getErrors();
+if ($errors) {
+    handleErrors($errors);
+}
+processAst($stmts);
+```
+
+Both the `throwOnError` option and the `getErrors()` method have been removed in PHP-Parser 3.0.
+Instead an instance of `ErrorHandler\Collecting` should be passed to the `parse()` method:
+
+```php
+$lexer = ...;
+$parser = (new ParserFactory)->create(ParserFactor::ONLY_PHP7, $lexer);
+
+$errorHandler = new ErrorHandler\Collecting;
+$stmts = $parser->parse($code, $errorHandler);
+if ($errorHandler->hasErrors()) {
+    handleErrors($errorHandler->getErrors());
+}
+processAst($stmts);
+```
+
+#### Multiple parser fallback in error recovery mode
+
+As a result of this change, if a `Multiple` parser is used (e.g. through the `ParserFactory` using
+`PREFER_PHP7` or `PREFER_PHP5`), it will now return the result of the first *non-throwing* parse. As
+parsing never throws in error recovery mode, the result from the first parser will always be
+returned.
+
+The PHP 7 parser is a superset of the PHP 5 parser, with the exceptions that `=& new` and
+`global $$foo->bar` are not supported (other differences are in representation only). The PHP 7
+parser will be able to recover from the error in both cases. For this reason, this change will
+likely pass unnoticed if you do not specifically test for this syntax.
+
+It is possible to restore the precise previous behavior with the following code:
+
+```php
+$lexer = ...;
+$parser7 = new Parser\Php7($lexer);
+$parser5 = new Parser\Php5($lexer);
+
+$errors7 = new ErrorHandler\Collecting();
+$stmts7 = $parser7->parse($code, $errors7);
+if ($errors7->hasErrors()) {
+    $errors5 = new ErrorHandler\Collecting();
+    $stmts5 = $parser5->parse($code, $errors5);
+    if (!$errors5->hasErrors()) {
+        // If PHP 7 parse has errors but PHP 5 parse has no errors, use PHP 5 result
+        return [$stmts5, $errors5];
+    }
+}
+// If PHP 7 succeeds or both fail use PHP 7 result
+return [$stmts7, $errors7];
+```
+
+#### Error handling in the lexer
+
+In order to support recovery from lexer errors, the signature of the `startLexing()` method changed
+to optionally accept an `ErrorHandler`:
+
+```php
+// OLD
+public function startLexing($code);
+// NEW
+public function startLexing($code, ErrorHandler $errorHandler = null);
+```
+
+If you use a custom lexer with overridden `startLexing()` method, it needs to be changed to accept
+the extra parameter. The value should be passed on to the parent method.
+
+#### Error checks in node constructors
+
+The constructors of certain nodes used to contain additional checks for semantic errors, such as
+creating a try block without either catch or finally. These checks have been moved from the node
+constructors into the parser. This allows recovery from such errors, as well as representing the
+resulting (invalid) AST.
+
+This means that certain error conditions are no longer checked for manually constructed nodes.
+
+### Removed methods, arguments, options
+
+The following methods, arguments or options have been removed:
+
+ * `Comment::setLine()`, `Comment::setText()`: Create new `Comment` instances instead.
+ * `Name::set()`, `Name::setFirst()`, `Name::setLast()`, `Name::append()`, `Name::prepend()`:
+    Use `Name::concat()` in combination with `Name::slice()` instead.
+ * `Error::getRawLine()`, `Error::setRawLine()`. Use `Error::getStartLine()` and
+   `Error::setStartLine()` instead.
+ * `Parser::getErrors()`. Use `ErrorHandler\Collecting` instead.
+ * `$separator` argument of `Name::toString()`. Use `strtr()` instead, if you really need it.
+ * `$cloneNodes` argument of `NodeTraverser::__construct()`. Explicitly clone nodes in the visitor
+   instead.
+ * `throwOnError` parser option. Use `ErrorHandler\Collecting` instead.
+
+### Miscellaneous
+
+ * The `NameResolver` will now resolve unqualified function and constant names in the global
+   namespace into fully qualified names. For example `foo()` in the global namespace resolves to
+   `\foo()`. For names where no static resolution is possible, a `namespacedName` attribute is
+   added now, containing the namespaced variant of the name.
+ * All methods on `PrettyPrinter\Standard` are now protected. Previously most of them were public.
+   The pretty printer should only be invoked using the `prettyPrint()`, `prettyPrintFile()` and
+   `prettyPrintExpr()` methods.
+ * The node dumper now prints numeric values that act as enums/flags in a string representation.
+   If node dumper results are used in tests, updates may be needed to account for this.
+ * The constants on `NameTraverserInterface` have been moved into the `NameTraverser` class.
+ * The emulative lexer now directly postprocesses tokens, instead of using `~__EMU__~` sequences.
+   This changes the protected API of the emulative lexer.
+ * The `Name::slice()` method now returns `null` for empty slices, previously `new Name([])` was
+   used. `Name::concat()` now also supports concatenation with `null`.

UPGRADE-4.0.md

@@ -0,0 +1,77 @@
+Upgrading from PHP-Parser 3.x to 4.0
+====================================
+
+### PHP version requirements
+
+PHP-Parser now requires PHP 7.0 or newer to run. It is however still possible to *parse* PHP 5.2-5.6
+source code, while running on a newer version.
+
+HHVM is no longer actively supported.
+
+### Changes to the node structure
+
+* Many subnodes that previously held simple strings now store `Identifier` nodes instead (or
+  `VarLikeIdentifier` nodes if they have form `$ident`). The constructors of the affected nodes will
+  automatically convert strings to `Identifier`s and `Identifier`s implement `__toString()`. As such
+  some code continues to work without changes, but anything using `is_string()`, type-strict
+  comparisons or strict-mode may require adjustment. The following is an exhaustive list of all
+  affected subnodes:
+
+   * `Const_::$name`
+   * `NullableType::$type` (for simple types)
+   * `Param::$type` (for simple types)
+   * `Expr\ClassConstFetch::$name`
+   * `Expr\Closure::$returnType` (for 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` (for simple types)
+   * `Stmt\Function_::$name`
+   * `Stmt\Function_::$returnType` (for 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`
+
+* Expression statements (`expr;`) are now represented using a `Stmt\Expression` node. Previously
+  these statements were directly represented as their constituent expression.
+* The `name` subnode of `Param` has been renamed to `var` and now contains a `Variable` rather than
+  a plain string.
+* The `name` subnode of `StaticVar` has been renamed to `var` and now contains a `Variable` rather
+  than a plain string.
+* The `var` subnode of `ClosureUse` now contains a `Variable` rather than a plain string.
+* The `var` subnode of `Catch_` now contains a `Variable` rather than a plain string.
+* The `alias` subnode of `UseUse` is now `null` if no explicit alias is given. As such,
+  `use Foo\Bar` and `use Foo\Bar as Bar` are now represented differently. The `getAlias()` method
+  can be used to get the effective alias, even if it is not explicitly given.
+
+### Miscellaneous
+
+* The indentation handling in the pretty printer has been changed (this is only relevant if you
+  extend the pretty printer). Previously indentation was automatic, and parts were excluded using
+  `pNoindent()`. Now no-indent is the default and newlines that require indentation should use
+  `$this->nl`.
+
+### Removed functionality
+
+* Removed `type` subnode on `Class_`, `ClassMethod` and `Property` nodes. Use `flags` instead.
+* The `ClassConst::isStatic()` method has been removed. Constants cannot have a static modifier.
+* The `NodeTraverser` no longer accepts `false` as a return value from a `leaveNode()` method.
+  `NodeTraverser::REMOVE_NODE` should be returned instead.
+* The `Node::setLine()` method has been removed. If you really need to, you can use `setAttribute()`
+  instead.
+* The misspelled `Class_::VISIBILITY_MODIFER_MASK` constant has been dropped in favor of
+  `Class_::VISIBILITY_MODIFIER_MASK`.
+* The XML serializer has been removed. As such, the classes `Serializer\XML`, and
+  `Unserializer\XML`, as well as the interfaces `Serializer` and `Unserializer` no longer exist.
+* The `BuilderAbstract` class has been removed. It's functionality is moved into `BuilderHelpers`.
+  However, this is an internal class and should not be used directly.
+* The `Autoloader` class has been removed in favor of relying on the Composer autoloader.

UPGRADE-5.0.md

@@ -0,0 +1,487 @@
+Upgrading from PHP-Parser 4.x to 5.0
+====================================
+
+### PHP version requirements
+
+PHP-Parser now requires PHP 7.4 or newer to run. It is however still possible to *parse* code for older versions, while running on a newer version.
+
+### PHP 5 parsing support
+
+The dedicated parser for PHP 5 has been removed. The PHP 7 parser now accepts a `PhpVersion` argument, which can be used to improve compatibility with older PHP versions.
+
+In particular, if an older `PhpVersion` is specified, then:
+
+ * For versions before PHP 7.0, `$foo =& new Bar()` assignments are allowed without error.
+ * For versions before PHP 7.0, invalid octal literals `089` are allowed without error.
+ * For versions before PHP 7.0, unicode escape sequences `\u{123}` in strings are not parsed.
+ * Type hints are interpreted as a class `Name` or as a built-in `Identifier` depending on PHP
+   version, for example `int` is treated as a class name on PHP 5.6 and as a built-in on PHP 7.0.
+
+However, some aspects of PHP 5 parsing are no longer supported:
+
+ * Some variables like `$$foo[0]` are valid in both PHP 5 and PHP 7, but have different interpretation. In that case, the PHP 7 AST will always be constructed (`($$foo)[0]` rather than `${$foo[0]}`).
+ * Declarations of the form `global $$var[0]` are not supported in PHP 7 and will cause a parse error. In error recovery mode, it is possible to continue parsing after such declarations.
+ * The PHP 7 parser will accept many constructs that are not valid in PHP 5. However, this was also true of the dedicated PHP 5 parser.
+
+The following symbols are affected by this removal:
+
+ * The `PhpParser\Parser\Php5` class has been removed.
+ * The `PhpParser\Parser\Multiple` class has been removed. While not strictly related to PHP 5 support, this functionality is no longer useful without it.
+ * The `PhpParser\ParserFactory::ONLY_PHP5` and `PREFER_PHP5` options have been removed.
+ * The `PhpParser\ParserFactory::PREFER_PHP7` option is now equivalent to `ONLY_PHP7`.
+
+### Changes to the parser factory
+
+The `ParserFactory::create()` method is deprecated in favor of three new methods that provide more fine-grained control over the PHP version being targeted:
+
+ * `createForNewestSupportedVersion()`: Use this if you don't know the PHP version of the code you're parsing. It's better to assume a too new version than a too old one.
+ * `createForHostVersion()`: Use this if you're parsing code for the PHP version you're running on.
+ * `createForVersion()`: Use this if you know the PHP version of the code you want to parse.
+
+In all cases, the PHP version is a fairly weak hint that is only used on a best-effort basis. The parser will usually accept code for newer versions if it does not have any backwards-compatibility implications.
+
+For example, if you specify version `"8.0"`, then `class ReadOnly {}` is treated as a valid class declaration, while using `public readonly int $prop` will lead to a parse error. However, `final public const X = Y;` will be accepted in both cases.
+
+```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"));
+```
+
+### Changes to the array destructuring representation
+
+Previously, the `list($x) = $y` destructuring syntax was represented using a `Node\Expr\List_`
+node, while `[$x] = $y` used a `Node\Expr\Array_` node, the same used for the creation (rather than
+destructuring) of arrays.
+
+Now, destructuring is always represented using `Node\Expr\List_`. The `kind` attribute with value
+`Node\Expr\List_::KIND_LIST` or `Node\Expr\List_::KIND_ARRAY` specifies which syntax was actually
+used.
+
+### Changes to the name representation
+
+Previously, `Name` nodes had a `parts` subnode, which stores an array of name parts, split by
+namespace separators. Now, `Name` nodes instead have a `name` subnode, which stores a plain string.
+
+For example, the name `Foo\Bar` was previously represented by `Name(parts: ['Foo', 'Bar'])` and is
+now represented by `Name(name: 'Foo\Bar')` instead.
+
+It is possible to convert the name to the previous representation using `$name->getParts()`. The
+`Name` constructor continues to accept both the string and the array representation.
+
+### Changes to the block representation
+
+Previously, code blocks `{ ... }` were always flattened into their parent statement list. For
+example `while ($x) { $a; { $b; } $c; }` would produce the same node structure as
+`if ($x) { $a; $b; $c; }`, namely a `Stmt\While_` node whose `stmts` subnode is an array of four
+statements.
+
+Now, the nested `{ $b; }` block is represented using an explicit `Stmt\Block` node. However, the
+outer `{ $a; { $b; } $c; }` block is still represented using a simple array in the `stmts` subnode.
+
+```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
+            )
+        )
+    )
+)
+```
+
+### Changes to the throw representation
+
+Previously, `throw` statements like `throw $e;` were represented using the `Stmt\Throw_` class,
+while uses inside other expressions (such as `$x ?? throw $e`) used the `Expr\Throw_` class.
+
+Now, `throw $e;` is represented as a `Stmt\Expression` that contains an `Expr\Throw_`. The
+`Stmt\Throw_` class has been removed.
+
+```php
+# Code
+throw $e;
+
+# Before
+Stmt_Throw(
+    expr: Expr_Variable(
+        name: e
+    )
+)
+
+# After
+Stmt_Expression(
+    expr: Expr_Throw(
+        expr: Expr_Variable(
+            name: e
+        )
+    )
+)
+```
+
+### Changes to comment assignment
+
+Previously, comments were assigned to all nodes starting at the same position. Now they will be
+assigned to the outer-most node only.
+
+```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
+    )
+)
+```
+
+### Renamed nodes
+
+A number of AST nodes have been renamed or moved in the AST hierarchy:
+
+ * `Node\Scalar\LNumber` is now `Node\Scalar\Int_`.
+ * `Node\Scalar\DNumber` is now `Node\Scalar\Float_`.
+ * `Node\Scalar\Encapsed` is now `Node\Scalar\InterpolatedString`.
+ * `Node\Scalar\EncapsedStringPart` is now `Node\InterpolatedStringPart` and no longer extends
+   `Node\Scalar` or `Node\Expr`.
+ * `Node\Expr\ArrayItem` is now `Node\ArrayItem` and no longer extends `Node\Expr`.
+ * `Node\Expr\ClosureUse` is now `Node\ClosureUse` and no longer extends `Node\Expr`.
+ * `Node\Stmt\DeclareDeclare` is now `Node\DeclareItem` and no longer extends `Node\Stmt`.
+ * `Node\Stmt\PropertyProperty` is now `Node\PropertyItem` and no longer extends `Node\Stmt`.
+ * `Node\Stmt\StaticVar` is now `Node\StaticVar` and no longer extends `Node\Stmt`.
+ * `Node\Stmt\UseUse` is now `Node\UseItem` and no longer extends `Node\Stmt`.
+
+The old class names have been retained as aliases for backwards compatibility. However, the `Node::getType()` method will now always return the new name (e.g. `ClosureUse` instead of `Expr_ClosureUse`).
+
+### Modifiers
+
+Modifier flags (as used by the `$flags` subnode of `Class_`, `ClassMethod`, `Property`, etc.) are now available as class constants on a separate `PhpParser\Modifiers` class, instead of being part of `PhpParser\Node\Stmt\Class_`, to make it clearer that these are used by many different nodes. The old constants are deprecated, but are still available.
+
+```
+PhpParser\Node\Stmt\Class_::MODIFIER_PUBLIC    -> PhpParser\Modifiers::PUBLIC
+PhpParser\Node\Stmt\Class_::MODIFIER_PROTECTED -> PhpParser\Modifiers::PROTECTED
+PhpParser\Node\Stmt\Class_::MODIFIER_PRIVATE   -> PhpParser\Modifiers::PRIVATE
+PhpParser\Node\Stmt\Class_::MODIFIER_STATIC    -> PhpParser\Modifiers::STATIC
+PhpParser\Node\Stmt\Class_::MODIFIER_ABSTRACT  -> PhpParser\Modifiers::ABSTRACT
+PhpParser\Node\Stmt\Class_::MODIFIER_FINAL     -> PhpParser\Modifiers::FINAL
+PhpParser\Node\Stmt\Class_::MODIFIER_READONLY  -> PhpParser\Modifiers::READONLY
+PhpParser\Node\Stmt\Class_::VISIBILITY_MODIFIER_MASK -> PhpParser\Modifiers::VISIBILITY_MASK
+```
+
+### Changes to node constructors
+
+Node constructor arguments accepting types now longer accept plain strings. Either an `Identifier` or `Name` (or `ComplexType`) should be passed instead. This affects the following constructor arguments:
+
+* The `'returnType'` key of `$subNodes` argument of `Node\Expr\ArrowFunction`.
+* The `'returnType'` key of `$subNodes` argument of `Node\Expr\Closure`.
+* The `'returnType'` key of `$subNodes` argument of `Node\Stmt\ClassMethod`.
+* The `'returnType'` key of `$subNodes` argument of `Node\Stmt\Function_`.
+* The `$type` argument of `Node\NullableType`.
+* The `$type` argument of `Node\Param`.
+* The `$type` argument of `Node\Stmt\Property`.
+* The `$type` argument of `Node\ClassConst`.
+
+To follow the previous behavior, an `Identifier` should be passed, which indicates a built-in type.
+
+### Changes to the pretty printer
+
+A number of changes to the standard pretty printer have been made, to make it match contemporary coding style conventions (and in particular PSR-12). Options to restore the previous behavior are not provided, but it is possible to override the formatting methods (such as `pStmt_ClassMethod`) with your preferred formatting.
+
+Return types are now formatted without a space before the `:`:
+
+```php
+# Before
+function test() : Type
+{
+}
+
+# After
+function test(): Type
+{
+}
+```
+
+`abstract` and `final` are now printed before visibility modifiers:
+
+```php
+# Before
+public abstract function test();
+
+# After
+abstract public function test();
+```
+
+A space is now printed between `use` and the following `(` for closures:
+
+```php
+# Before
+function () use($var) {
+};
+
+# After
+function () use ($var) {
+};
+```
+
+Backslashes in single-quoted strings are now only printed if they are necessary:
+
+```php
+# Before
+'Foo\\Bar';
+'\\\\';
+
+# After
+'Foo\Bar';
+'\\\\';
+```
+
+`else if` structures will now omit redundant parentheses:
+
+```php
+# Before
+else {
+    if ($x) {
+        // ...
+    }
+}
+
+# After
+else if ($x) {
+     // ...
+}
+```
+
+The pretty printer now accepts a `phpVersion` option, which accepts a `PhpVersion` object and defaults to PHP 7.4. The pretty printer will make formatting choices to make the code valid for that version. It currently controls the following behavior:
+
+* For PHP >= 7.0 (default), short array syntax `[]` will be used by default. This does not affect nodes that specify an explicit array syntax using the `kind` attribute.
+* For PHP >= 7.0 (default), parentheses around `yield` expressions will only be printed when necessary. Previously, parentheses were always printed, even if `yield` was used as a statement.
+* For PHP >= 7.1 (default), the short array syntax `[]` will be used for destructuring by default (instead of `list()`). This does not affect nodes that specify and explicit syntax using the `kind` attribute.
+* For PHP >= 7.3 (default), a newline is no longer forced after heredoc/nowdoc strings, as the requirement for this has been removed with the introduction of flexible heredoc/nowdoc strings.
+* For PHP >= 7.3 (default), heredoc/nowdoc strings are now indented just like regular code. This was allowed with the introduction of flexible heredoc/nowdoc strings.
+
+### Changes to precedence handling in the pretty printer
+
+The pretty printer now more accurately models operator precedence. Especially for unary operators, less unnecessary parentheses will be printed. Conversely, many bugs where semantically meaningful parentheses were omitted have been fixed.
+
+To support these changes, precedence is now handled differently in the pretty printer. The internal `p()` method, which is used to recursively print nodes, now has the following signature:
+```php
+protected function p(
+    Node $node, int $precedence = self::MAX_PRECEDENCE, int $lhsPrecedence = self::MAX_PRECEDENCE,
+    bool $parentFormatPreserved = false
+): string;
+```
+
+The `$precedence` is the precedence of the direct parent operator (if any), while `$lhsPrecedence` is that precedence of the nearest binary operator on whose left-hand-side the node occurs. For unary operators, only the `$lhsPrecedence` is relevant.
+
+Recursive calls in pretty-printer methods should generally continue calling `p()` without additional parameters. However, pretty-printer methods for operators that participate in precedence resolution need to be adjusted. For example, typical implementations for operators looks as follows now:
+
+```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);
+}
+```
+
+The new `$precedence` and `$lhsPrecedence` arguments need to be passed down to the `pInfixOp()`, `pPrefixOp()` and `pPostfixOp()` methods.
+
+### Changes to the node traverser
+
+If there are multiple visitors, the node traverser will now call `leaveNode()` and `afterTraverse()` methods in the reverse order of the corresponding `enterNode()` and `beforeTraverse()` calls:
+
+```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);
+```
+
+Additionally, the special `NodeVisitor` return values have been moved from `NodeTraverser` to `NodeVisitor`. The old names are deprecated, but still available.
+
+```php
+PhpParser\NodeTraverser::REMOVE_NODE -> PhpParser\NodeVisitor::REMOVE_NODE
+PhpParser\NodeTraverser::DONT_TRAVERSE_CHILDREN -> PhpParser\NodeVisitor::DONT_TRAVERSE_CHILDREN
+PhpParser\NodeTraverser::DONT_TRAVERSE_CURRENT_AND_CHILDREN -> PhpParser\NodeVisitor::DONT_TRAVERSE_CURRENT_AND_CHILDREN
+PhpParser\NodeTraverser::STOP_TRAVERSAL -> PhpParser\NodeVisitor::STOP_TRAVERSAL
+```
+
+Visitors can now also be passed directly to the `NodeTraverser` constructor:
+
+```php
+# Before (and still supported)
+$traverser = new NodeTraverser();
+$traverser->addVisitor(new NameResolver());
+
+# After
+$traverser = new NodeTraverser(new NameResolver());
+```
+
+### Changes to token representation
+
+Tokens are now internally represented using the `PhpParser\Token` class, which exposes the same base interface as
+the `PhpToken` class introduced in PHP 8.0. On PHP 8.0 or newer, `PhpParser\Token` extends from `PhpToken`, otherwise
+it extends from a polyfill implementation. The most important parts of the interface may be summarized as follows:
+
+```php
+class Token {
+    public int $id;
+    public string $text;
+    public int $line;
+    public int $pos;
+
+    public function is(int|string|array $kind): bool;
+}
+```
+
+The token array is now an array of `Token`s, rather than an array of arrays and strings.
+Additionally, the token array is now terminated by a sentinel token with ID 0.
+
+### Changes to the lexer
+
+The lexer API is reduced to a single `Lexer::tokenize()` method, which returns an array of tokens. The `startLexing()` and `getNextToken()` methods have been removed.
+
+Responsibility for determining start and end attributes for nodes has been moved from the lexer to the parser. The lexer no longer accepts an options array. The `usedAttributes` option has been removed without replacement, and the parser will now unconditionally add the `comments`, `startLine`, `endLine`, `startFilePos`, `endFilePos`, `startTokenPos` and `endTokenPos` attributes.
+
+There should no longer be a need to directly interact with the `Lexer` for end users, as the `ParserFactory` will create an appropriate instance, and no additional configuration of the lexer is necessary. To use formatting-preserving pretty printing, the setup boilerplate changes as follows:
+
+```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 = $lexer->getTokens();
+
+$traverser = new NodeTraverser(new NodeVisitor\CloningVisitor());
+$newStmts = $traverser->traverse($oldStmts);
+```
+
+### Miscellaneous changes
+
+ * The deprecated `Builder\Param::setTypeHint()` method has been removed in favor of `Builder\Param::setType()`.
+ * The deprecated `Error` constructor taking a start line has been removed. Pass `['startLine' => $startLine]` attributes instead.
+ * The deprecated `Comment::getLine()`, `Comment::getTokenPos()` and `Comment::getFilePos()` methods have been removed. Use `Comment::getStartLine()`, `Comment::getStartTokenPos()` and `Comment::getStartFilePos()` instead.
+ * `Comment::getReformattedText()` now normalizes CRLF newlines to LF newlines.
+ * The `Node::getLine()` method has been deprecated. Use `Node::getStartLine()` instead.

bin/php-parse

@@ -0,0 +1,206 @@
+#!/usr/bin/env php
+<?php
+
+foreach ([__DIR__ . '/../../../autoload.php', __DIR__ . '/../vendor/autoload.php'] as $file) {
+    if (file_exists($file)) {
+        require $file;
+        break;
+    }
+}
+
+ini_set('xdebug.max_nesting_level', 3000);
+
+// Disable Xdebug var_dump() output truncation
+ini_set('xdebug.var_display_max_children', -1);
+ini_set('xdebug.var_display_max_data', -1);
+ini_set('xdebug.var_display_max_depth', -1);
+
+list($operations, $files, $attributes) = parseArgs($argv);
+
+/* Dump nodes by default */
+if (empty($operations)) {
+    $operations[] = 'dump';
+}
+
+if (empty($files)) {
+    showHelp("Must specify at least one file.");
+}
+
+$parser = (new PhpParser\ParserFactory())->createForVersion($attributes['version']);
+$dumper = new PhpParser\NodeDumper([
+    'dumpComments' => true,
+    'dumpPositions' => $attributes['with-positions'],
+]);
+$prettyPrinter = new PhpParser\PrettyPrinter\Standard;
+
+$traverser = new PhpParser\NodeTraverser();
+$traverser->addVisitor(new PhpParser\NodeVisitor\NameResolver);
+
+foreach ($files as $file) {
+    if ($file === '-') {
+        $code = file_get_contents('php://stdin');
+        fwrite(STDERR, "====> Stdin:\n");
+    } else if (strpos($file, '<?php') === 0) {
+        $code = $file;
+        fwrite(STDERR, "====> Code $code\n");
+    } else {
+        if (!file_exists($file)) {
+            fwrite(STDERR, "File $file does not exist.\n");
+            exit(1);
+        }
+
+        $code = file_get_contents($file);
+        fwrite(STDERR, "====> File $file:\n");
+    }
+
+    if ($attributes['with-recovery']) {
+        $errorHandler = new PhpParser\ErrorHandler\Collecting;
+        $stmts = $parser->parse($code, $errorHandler);
+        foreach ($errorHandler->getErrors() as $error) {
+            $message = formatErrorMessage($error, $code, $attributes['with-column-info']);
+            fwrite(STDERR, $message . "\n");
+        }
+        if (null === $stmts) {
+            continue;
+        }
+    } else {
+        try {
+            $stmts = $parser->parse($code);
+        } catch (PhpParser\Error $error) {
+            $message = formatErrorMessage($error, $code, $attributes['with-column-info']);
+            fwrite(STDERR, $message . "\n");
+            exit(1);
+        }
+    }
+
+    foreach ($operations as $operation) {
+        if ('dump' === $operation) {
+            fwrite(STDERR, "==> Node dump:\n");
+            echo $dumper->dump($stmts, $code), "\n";
+        } elseif ('pretty-print' === $operation) {
+            fwrite(STDERR, "==> Pretty print:\n");
+            echo $prettyPrinter->prettyPrintFile($stmts), "\n";
+        } elseif ('json-dump' === $operation) {
+            fwrite(STDERR, "==> JSON dump:\n");
+            echo json_encode($stmts, JSON_PRETTY_PRINT), "\n";
+        } elseif ('var-dump' === $operation) {
+            fwrite(STDERR, "==> var_dump():\n");
+            var_dump($stmts);
+        } elseif ('resolve-names' === $operation) {
+            fwrite(STDERR, "==> Resolved names.\n");
+            $stmts = $traverser->traverse($stmts);
+        }
+    }
+}
+
+function formatErrorMessage(PhpParser\Error $e, $code, $withColumnInfo) {
+    if ($withColumnInfo && $e->hasColumnInfo()) {
+        return $e->getMessageWithColumnInfo($code);
+    } else {
+        return $e->getMessage();
+    }
+}
+
+function showHelp($error = '') {
+    if ($error) {
+        fwrite(STDERR, $error . "\n\n");
+    }
+    fwrite($error ? STDERR : STDOUT, <<<'OUTPUT'
+Usage: php-parse [operations] file1.php [file2.php ...]
+   or: php-parse [operations] "<?php code"
+Turn PHP source code into an abstract syntax tree.
+
+Operations is a list of the following options (--dump by default):
+
+    -d, --dump              Dump nodes using NodeDumper
+    -p, --pretty-print      Pretty print file using PrettyPrinter\Standard
+    -j, --json-dump         Print json_encode() result
+        --var-dump          var_dump() nodes (for exact structure)
+    -N, --resolve-names     Resolve names using NodeVisitor\NameResolver
+    -c, --with-column-info  Show column-numbers for errors (if available)
+    -P, --with-positions    Show positions in node dumps
+    -r, --with-recovery     Use parsing with error recovery
+        --version=VERSION   Target specific PHP version (default: newest)
+    -h, --help              Display this page
+
+Example:
+    php-parse -d -p -N -d file.php
+
+    Dumps nodes, pretty prints them, then resolves names and dumps them again.
+
+
+OUTPUT
+    );
+    exit($error ? 1 : 0);
+}
+
+function parseArgs($args) {
+    $operations = [];
+    $files = [];
+    $attributes = [
+        'with-column-info' => false,
+        'with-positions' => false,
+        'with-recovery' => false,
+        'version' => PhpParser\PhpVersion::getNewestSupported(),
+    ];
+
+    array_shift($args);
+    $parseOptions = true;
+    foreach ($args as $arg) {
+        if (!$parseOptions) {
+            $files[] = $arg;
+            continue;
+        }
+
+        switch ($arg) {
+            case '--dump':
+            case '-d':
+                $operations[] = 'dump';
+                break;
+            case '--pretty-print':
+            case '-p':
+                $operations[] = 'pretty-print';
+                break;
+            case '--json-dump':
+            case '-j':
+                $operations[] = 'json-dump';
+                break;
+            case '--var-dump':
+                $operations[] = 'var-dump';
+                break;
+            case '--resolve-names':
+            case '-N';
+                $operations[] = 'resolve-names';
+                break;
+            case '--with-column-info':
+            case '-c';
+                $attributes['with-column-info'] = true;
+                break;
+            case '--with-positions':
+            case '-P':
+                $attributes['with-positions'] = true;
+                break;
+            case '--with-recovery':
+            case '-r':
+                $attributes['with-recovery'] = true;
+                break;
+            case '--help':
+            case '-h';
+                showHelp();
+                break;
+            case '--':
+                $parseOptions = false;
+                break;
+            default:
+                if (preg_match('/^--version=(.*)$/', $arg, $matches)) {
+                    $attributes['version'] = PhpParser\PhpVersion::fromString($matches[1]);
+                } elseif ($arg[0] === '-' && \strlen($arg[0]) > 1) {
+                    showHelp("Invalid operation $arg.");
+                } else {
+                    $files[] = $arg;
+                }
+        }
+    }
+
+    return [$operations, $files, $attributes];
+}

bin/php-parse.php

@@ -1,161 +0,0 @@
-#!/usr/bin/env php
-<?php
-
-require __DIR__ . '/../lib/bootstrap.php';
-
-ini_set('xdebug.max_nesting_level', 3000);
-
-// Disable XDebug var_dump() output truncation
-ini_set('xdebug.var_display_max_children', -1);
-ini_set('xdebug.var_display_max_data', -1);
-ini_set('xdebug.var_display_max_depth', -1);
-
-list($operations, $files, $attributes) = parseArgs($argv);
-
-/* Dump nodes by default */
-if (empty($operations)) {
-    $operations[] = 'dump';
-}
-
-if (empty($files)) {
-    showHelp("Must specify at least one file.");
-}
-
-$lexer = new PhpParser\Lexer\Emulative(array('usedAttributes' => array(
-    'startLine', 'endLine', 'startFilePos', 'endFilePos'
-)));
-$parser = new PhpParser\Parser($lexer);
-$dumper = new PhpParser\NodeDumper;
-$prettyPrinter = new PhpParser\PrettyPrinter\Standard;
-$serializer = new PhpParser\Serializer\XML;
-
-$traverser = new PhpParser\NodeTraverser();
-$traverser->addVisitor(new PhpParser\NodeVisitor\NameResolver);
-
-foreach ($files as $file) {
-    if (strpos($file, '<?php') === 0) {
-        $code = $file;
-        echo "====> Code $code\n";
-    } else {
-        if (!file_exists($file)) {
-            die("File $file does not exist.\n");
-        }
-
-        $code = file_get_contents($file);
-        echo "====> File $file:\n";
-    }
-
-    try {
-        $stmts = $parser->parse($code);
-    } catch (PhpParser\Error $e) {
-        if ($attributes['with-column-info'] && $e->hasColumnInfo()) {
-            $startLine = $e->getStartLine();
-            $endLine = $e->getEndLine();
-            $startColumn = $e->getStartColumn($code);
-            $endColumn   = $e->getEndColumn($code);
-            $message .= $e->getRawMessage() . " from $startLine:$startColumn to $endLine:$endColumn";
-        } else {
-            $message = $e->getMessage();
-        }
-
-        die($message . "\n");
-    }
-
-    foreach ($operations as $operation) {
-        if ('dump' === $operation) {
-            echo "==> Node dump:\n";
-            echo $dumper->dump($stmts), "\n";
-        } elseif ('pretty-print' === $operation) {
-            echo "==> Pretty print:\n";
-            echo $prettyPrinter->prettyPrintFile($stmts), "\n";
-        } elseif ('serialize-xml' === $operation) {
-            echo "==> Serialized XML:\n";
-            echo $serializer->serialize($stmts), "\n";
-        } elseif ('var-dump' === $operation) {
-            echo "==> var_dump():\n";
-            var_dump($stmts);
-        } elseif ('resolve-names' === $operation) {
-            echo "==> Resolved names.\n";
-            $stmts = $traverser->traverse($stmts);
-        }
-    }
-}
-
-function showHelp($error) {
-    die($error . "\n\n" .
-        <<<OUTPUT
-Usage: php php-parse.php [operations] file1.php [file2.php ...]
-   or: php php-parse.php [operations] "<?php code"
-Turn PHP source code into an abstract syntax tree.
-
-Operations is a list of the following options (--dump by default):
-
-    -d, --dump              Dump nodes using NodeDumper
-    -p, --pretty-print      Pretty print file using PrettyPrinter\Standard
-        --serialize-xml     Serialize nodes using Serializer\XML
-        --var-dump          var_dump() nodes (for exact structure)
-    -N, --resolve-names     Resolve names using NodeVisitor\NameResolver
-    -c, --with-column-info  Show column-numbers for errors (if available)
-
-Example:
-    php php-parse.php -d -p -N -d file.php
-
-    Dumps nodes, pretty prints them, then resolves names and dumps them again.
-
-
-OUTPUT
-    );
-}
-
-function parseArgs($args) {
-    $operations = array();
-    $files = array();
-    $attributes = array(
-        'with-column-info' => false,
-    );
-
-    array_shift($args);
-    $parseOptions = true;
-    foreach ($args as $arg) {
-        if (!$parseOptions) {
-            $files[] = $arg;
-            continue;
-        }
-
-        switch ($arg) {
-            case '--dump':
-            case '-d':
-                $operations[] = 'dump';
-                break;
-            case '--pretty-print':
-            case '-p':
-                $operations[] = 'pretty-print';
-                break;
-            case '--serialize-xml':
-                $operations[] = 'serialize-xml';
-                break;
-            case '--var-dump':
-                $operations[] = 'var-dump';
-                break;
-            case '--resolve-names':
-            case '-N';
-                $operations[] = 'resolve-names';
-                break;
-            case '--with-column-info':
-            case '-c';
-                $attributes['with-column-info'] = true;
-                break;
-            case '--':
-                $parseOptions = false;
-                break;
-            default:
-                if ($arg[0] === '-') {
-                    showHelp("Invalid operation $arg.");
-                } else {
-                    $files[] = $arg;
-                }
-        }
-    }
-
-    return array($operations, $files, $attributes);
-}

composer.json

@@ -1,8 +1,11 @@
 {
     "name": "nikic/php-parser",
-    "description": "A PHP parser written in PHP",
-    "keywords": ["php", "parser"],
     "type": "library",
+    "description": "A PHP parser written in PHP",
+    "keywords": [
+        "php",
+        "parser"
+    ],
     "license": "BSD-3-Clause",
     "authors": [
         {
@@ -10,15 +13,31 @@
         }
     ],
     "require": {
-        "php": ">=5.3",
-        "ext-tokenizer": "*"
+        "php": ">=7.4",
+        "ext-tokenizer": "*",
+        "ext-json": "*",
+        "ext-ctype": "*"
     },
-    "autoload": {
-        "files": ["lib/bootstrap.php"]
+    "require-dev": {
+        "phpunit/phpunit": "^7.0 || ^8.0 || ^9.0",
+        "ircmaxell/php-yacc": "^0.0.7"
     },
     "extra": {
         "branch-alias": {
-            "dev-master": "1.4-dev"
+            "dev-master": "5.0-dev"
         }
-    }
+    },
+    "autoload": {
+        "psr-4": {
+            "PhpParser\\": "lib/PhpParser"
+        }
+    },
+    "autoload-dev": {
+        "psr-4": {
+            "PhpParser\\": "test/PhpParser/"
+        }
+    },
+    "bin": [
+        "bin/php-parse"
+    ]
 }

doc/0_Introduction.markdown

@@ -1,7 +1,7 @@
 Introduction
 ============
 
-This project is a PHP 5.2 to PHP 5.6 parser **written in PHP itself**.
+This project is a PHP parser **written in PHP itself**.
 
 What is this for?
 -----------------
@@ -13,31 +13,47 @@ application dealing with code programmatically. A parser constructs an [Abstract
 There are other ways of processing source code. One that PHP supports natively is using the
 token stream generated by [`token_get_all`][2]. The token stream is much more low level than
 the AST and thus has different applications: It allows to also analyze the exact formatting of
-a file. On the other hand the token stream is much harder to deal with for more complex analysis.
-For example an AST abstracts away the fact that in PHP variables can be written as `$foo`, but also
+a file. On the other hand, the token stream is much harder to deal with for more complex analysis.
+For example, an AST abstracts away the fact that, in PHP, variables can be written as `$foo`, but also
 as `$$bar`, `${'foobar'}` or even `${!${''}=barfoo()}`. You don't have to worry about recognizing
 all the different syntaxes from a stream of tokens.
 
-Another questions is: Why would I want to have a PHP parser *written in PHP*? Well, PHP might not be
+Another question is: Why would I want to have a PHP parser *written in PHP*? Well, PHP might not be
 a language especially suited for fast parsing, but processing the AST is much easier in PHP than it
-would be in other, faster languages like C. Furthermore the people most probably wanting to do
+would be in other, faster languages like C. Furthermore the people most likely wanting to do
 programmatic PHP code analysis are incidentally PHP developers, not C developers.
 
 What can it parse?
 ------------------
 
-The parser uses a PHP 5.6 compliant grammar, which is backwards compatible with all PHP version from PHP 5.2
-upwards (and maybe older).
+The parser supports parsing PHP 7 and PHP 8 code, with the following exceptions:
+
+ * Namespaced names containing whitespace (e.g. `Foo \ Bar` instead of `Foo\Bar`) are not supported.
+   These are illegal in PHP 8, but are legal in earlier versions. However, PHP-Parser does not
+   support them for any version.
+
+PHP-Parser 4.x had full support for parsing PHP 5. PHP-Parser 5.x has only limited support, with the
+following caveats:
+
+ * Some variable expressions like `$$foo[0]` are valid in both PHP 5 and PHP 7, but have different 
+   interpretation. In such cases, the PHP 7 AST will always be constructed (using `($$foo)[0]`
+   rather than `${$foo[0]}`).
+ * Declarations of the form `global $$var[0]` are not supported in PHP 7 and will cause a parse 
+   error. In error recovery mode, it is possible to continue parsing after such declarations.
 
 As the parser is based on the tokens returned by `token_get_all` (which is only able to lex the PHP
-version it runs on), additionally a wrapper for emulating new tokens from 5.3, 5.4, 5.5 and 5.6 is provided.
-This allows to parse PHP 5.6 source code running on PHP 5.3, for example. This emulation is very hacky and not
-perfect, but it should work well on any sane code.
+version it runs on), additionally a wrapper for emulating tokens from newer versions is provided.
+This allows to parse PHP 8.3 source code running on PHP 7.4, for example. This emulation is not
+perfect, but works well in practice.
+
+Finally, it should be noted that the parser aims to accept all valid code, not reject all invalid
+code. It will generally accept code that is only valid in newer versions (even when targeting an
+older one), and accept code that is syntactically correct, but would result in a compiler error.
 
 What output does it produce?
 ----------------------------
 
-The parser produces an [Abstract Syntax Tree][1] (AST) also known as a node tree. How this looks like
+The parser produces an [Abstract Syntax Tree][1] (AST) also known as a node tree. How this looks
 can best be seen in an example. The program `<?php echo 'Hi', 'World';` will give you a node tree
 roughly looking like this:
 
@@ -57,24 +73,24 @@ array(
 ```
 
 This matches the structure of the code: An echo statement, which takes two strings as expressions,
-with the values `Hi` and `World!`.
+with the values `Hi` and `World`.
 
 You can also see that the AST does not contain any whitespace information (but most comments are saved).
-So using it for formatting analysis is not possible.
+However, it does retain accurate position information, which can be used to inspect precise formatting.
 
 What else can it do?
 --------------------
 
-Apart from the parser itself this package also bundles support for some other, related features:
+Apart from the parser itself, this package also bundles support for some other, related features:
 
  * Support for pretty printing, which is the act of converting an AST into PHP code. Please note
    that "pretty printing" does not imply that the output is especially pretty. It's just how it's
    called ;)
- * Support for serializing and unserializing the node tree to XML
- * Support for dumping the node tree in a human readable form (see the section above for an
-   example of how the output looks like)
- * Infrastructure for traversing and changing the AST (node traverser and node visitors)
- * A node visitor for resolving namespaced names
+ * Support for serializing and unserializing the node tree to JSON.
+ * Support for dumping the node tree in a human-readable form (see the section above for an
+   example of how the output looks like).
+ * Infrastructure for traversing and changing the AST (node traverser and node visitors).
+ * A node visitor for resolving namespaced names.
 
  [0]: http://en.wikipedia.org/wiki/Static_program_analysis
  [1]: http://en.wikipedia.org/wiki/Abstract_syntax_tree

doc/1_Installation.markdown

@@ -1,31 +0,0 @@
-Installation
-============
-
-There are multiple ways to include the PHP parser into your project:
-
-Installing via Composer
------------------------
-
-Run the following command inside your project:
-
-    php composer.phar require nikic/php-parser
-
-If you haven't installed [Composer][1] yet, you can do so using:
-
-    curl -s http://getcomposer.org/installer | php
-
-Installing as a Git Submodule
------------------------------
-
-Run the following command to install the parser into the `vendor/PHP-Parser` folder:
-
-    git submodule add git://github.com/nikic/PHP-Parser.git vendor/PHP-Parser
-
-Installing from the Zip- or Tarball
------------------------------------
-
-Download the latest version from [the download page][2], unpack it and move the files somewhere into your project.
-
-
- [1]: https://getcomposer.org/
- [2]: https://github.com/nikic/PHP-Parser/tags

doc/2_Usage_of_basic_components.markdown

@@ -6,82 +6,144 @@ This document explains how to use the parser, the pretty printer and the node tr
 Bootstrapping
 -------------
 
-The library needs to register a class autoloader. You can either use the `vendor/autoload.php` file generated by
-Composer or by including the bundled `lib/bootstrap.php` file:
+To bootstrap the library, include the autoloader generated by composer:
 
 ```php
-<?php
-require 'path/to/PHP-Parser/lib/bootstrap.php';
-// Or, if you're using Composer:
 require 'path/to/vendor/autoload.php';
 ```
 
-Additionally you may want to set the `xdebug.max_nesting_level` ini option to a higher value:
+Additionally, you may want to set the `xdebug.max_nesting_level` ini option to a higher value:
 
 ```php
-<?php
 ini_set('xdebug.max_nesting_level', 3000);
 ```
 
-This ensures that there will be no errors when traversing highly nested node trees.
+This ensures that there will be no errors when traversing highly nested node trees. However, it is
+preferable to disable Xdebug completely, as it can easily make this library more than five times
+slower.
 
 Parsing
 -------
 
-In order to parse some source code you first have to create a `PhpParser\Parser` object, which
-needs to be passed a `PhpParser\Lexer` instance:
+In order to parse code, you first have to create a parser instance:
 
 ```php
-<?php
+use PhpParser\ParserFactory;
+use PhpParser\PhpVersion;
 
-$parser = new PhpParser\Parser(new PhpParser\Lexer);
-// or
-$parser = new PhpParser\Parser(new PhpParser\Lexer\Emulative);
+// 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'));
 ```
 
-Use of the emulative lexer is required if you want to parse PHP code from newer versions than the one
-you're running on. For example it will allow you to parse PHP 5.6 code while running on PHP 5.3.
+Which version you should target depends on your use case. In many cases you will want to use the
+host version, as people typically analyze code for the version they are running on. However, when
+analyzing arbitrary code you are usually best off using the newest supported version, which tends
+to accept the widest range of code (unless there are breaking changes in PHP).
 
-Subsequently you can pass PHP code (including the opening `<?php` tag) to the `parse` method in order to
-create a syntax tree. If a syntax error is encountered, an `PhpParser\Error` exception will be thrown:
+The `createXYZ()` methods optionally accept an array of lexer options. Some use cases that require
+customized lexer options are discussed in the [lexer documentation](component/Lexer.markdown).
+
+Subsequently, you can pass PHP code (including the opening `<?php` tag) to the `parse()` method in
+order to create a syntax tree. If a syntax error is encountered, a `PhpParser\Error` exception will
+be thrown by default:
 
 ```php
 <?php
-$code = '<?php // some code';
+use PhpParser\Error;
+use PhpParser\ParserFactory;
 
-$parser = new PhpParser\Parser(new PhpParser\Lexer\Emulative);
+$code = <<<'CODE'
+<?php
+function printLine($msg) {
+    echo $msg, "\n";
+}
+printLine('Hello World!!!');
+CODE;
+
+$parser = (new ParserFactory())->createForHostVersion();
 
 try {
     $stmts = $parser->parse($code);
     // $stmts is an array of statement nodes
-} catch (PhpParser\Error $e) {
-    echo 'Parse Error: ', $e->getMessage();
+} catch (Error $e) {
+    echo 'Parse Error: ', $e->getMessage(), "\n";
 }
 ```
 
 A parser instance can be reused to parse multiple files.
 
-Node tree
----------
+Node dumping
+------------
 
-If you use the above code with `$code = "<?php echo 'Hi ', hi\\getTarget();"` the parser will
-generate a node tree looking like this:
+To dump the abstract syntax tree in human-readable form, a `NodeDumper` can be used:
+
+```php
+<?php
+use PhpParser\NodeDumper;
+
+$nodeDumper = new NodeDumper;
+echo $nodeDumper->dump($stmts), "\n";
+```
+
+For the sample code from the previous section, this will produce the following output:
 
 ```
 array(
-    0: Stmt_Echo(
-        exprs: array(
-            0: Scalar_String(
-                value: Hi
+    0: Stmt_Function(
+        attrGroups: array(
+        )
+        byRef: false
+        name: Identifier(
+            name: printLine
+        )
+        params: array(
+            0: Param(
+                attrGroups: array(
+                )
+                flags: 0
+                type: null
+                byRef: false
+                variadic: false
+                var: Expr_Variable(
+                    name: msg
+                )
+                default: null
             )
-            1: Expr_FuncCall(
-                name: Name(
-                    parts: array(
-                        0: hi
-                        1: getTarget
+        )
+        returnType: null
+        stmts: array(
+            0: Stmt_Echo(
+                exprs: array(
+                    0: Expr_Variable(
+                        name: msg
+                    )
+                    1: Scalar_String(
+                        value:
+
                     )
                 )
-                args: array(
+            )
+        )
+    )
+    1: Stmt_Expression(
+        expr: Expr_FuncCall(
+            name: Name(
+                name: printLine
+            )
+            args: array(
+                0: Arg(
+                    name: null
+                    value: Scalar_String(
+                        value: Hello World!!!
+                    )
+                    byRef: false
+                    unpack: false
                 )
             )
         )
@@ -89,15 +151,35 @@ array(
 )
 ```
 
-Thus `$stmts` will contain an array with only one node, with this node being an instance of
-`PhpParser\Node\Stmt\Echo_`.
+You can also use the `php-parse` script to obtain such a node dump by calling it either with a file
+name or code string:
 
-As PHP is a large language there are approximately 140 different nodes. In order to make work
+```sh
+vendor/bin/php-parse file.php
+vendor/bin/php-parse "<?php foo();"
+```
+
+This can be very helpful if you want to quickly check how certain syntax is represented in the AST.
+
+Node tree structure
+-------------------
+
+Looking at the node dump above, you can see that `$stmts` for this example code is an array of two
+nodes, a `Stmt_Function` and a `Stmt_Expression`. The corresponding class names are:
+
+ * `Stmt_Function -> PhpParser\Node\Stmt\Function_`
+ * `Stmt_Expression -> PhpParser\Node\Stmt\Expression`
+
+The additional `_` at the end of the first class name is necessary, because `Function` is a
+reserved keyword. Many node class names in this library have a trailing `_` to avoid clashing with
+a keyword.
+
+As PHP is a large language there are approximately 140 different nodes. In order to make working
 with them easier they are grouped into three categories:
 
  * `PhpParser\Node\Stmt`s are statement nodes, i.e. language constructs that do not return
    a value and can not occur in an expression. For example a class definition is a statement.
-   It doesn't return a value and you can't write something like `func(class A {});`.
+   It doesn't return a value, and you can't write something like `func(class A {});`.
  * `PhpParser\Node\Expr`s are expression nodes, i.e. language constructs that return a value
    and thus can occur in other expressions. Examples of expressions are `$var`
    (`PhpParser\Node\Expr\Variable`) and `func()` (`PhpParser\Node\Expr\FuncCall`).
@@ -108,8 +190,9 @@ with them easier they are grouped into three categories:
  * There are some nodes not in either of these groups, for example names (`PhpParser\Node\Name`)
    and call arguments (`PhpParser\Node\Arg`).
 
-Some node class names have a trailing `_`. This is used whenever the class name would otherwise clash
-with a PHP keyword.
+The `Node\Stmt\Expression` node is somewhat confusing in that it contains both the terms "statement"
+and "expression". This node distinguishes `expr`, which is a `Node\Expr`, from `expr;`, which is
+an "expression statement" represented by `Node\Stmt\Expression` and containing `expr` as a sub-node.
 
 Every node has a (possibly zero) number of subnodes. You can access subnodes by writing
 `$node->subNodeName`. The `Stmt\Echo_` node has only one subnode `exprs`. So in order to access it
@@ -123,25 +206,29 @@ without the `PhpParser\Node\` prefix and `\` replaced with `_`. It also does not
 It is possible to associate custom metadata with a node using the `setAttribute()` method. This data
 can then be retrieved using `hasAttribute()`, `getAttribute()` and `getAttributes()`.
 
-By default the lexer adds the `startLine`, `endLine` and `comments` attributes. `comments` is an array
-of `PhpParser\Comment[\Doc]` instances.
+By default, the parser adds the `startLine`, `endLine`, `startTokenPos`, `endTokenPos`,
+`startFilePos`, `endFilePos` and `comments` attributes. `comments` is an array of
+`PhpParser\Comment[\Doc]` instances.
 
-The start line can also be accessed using `getLine()`/`setLine()` (instead of `getAttribute('startLine')`).
-The last doc comment from the `comments` attribute can be obtained using `getDocComment()`.
+The pre-defined attributes can also be accessed using `getStartLine()` instead of
+`getAttribute('startLine')`, and so on. The last doc comment from the `comments` attribute can be
+obtained using `getDocComment()`.
 
 Pretty printer
 --------------
 
-The pretty printer component compiles the AST back to PHP code. As the parser does not retain formatting
-information the formatting is done using a specified scheme. Currently there is only one scheme available,
-namely `PhpParser\PrettyPrinter\Standard`.
+The pretty printer component compiles the AST back to PHP code according to a specified scheme.
+Currently, there is only one scheme available, namely `PhpParser\PrettyPrinter\Standard`.
 
 ```php
-<?php
+use PhpParser\Error;
+use PhpParser\ParserFactory;
+use PhpParser\PrettyPrinter;
+
 $code = "<?php echo 'Hi ', hi\\getTarget();";
 
-$parser = new PhpParser\Parser(new PhpParser\Lexer);
-$prettyPrinter = new PhpParser\PrettyPrinter\Standard;
+$parser = (new ParserFactory())->createForHostVersion();
+$prettyPrinter = new PrettyPrinter\Standard();
 
 try {
     // parse
@@ -158,16 +245,16 @@ try {
     $code = $prettyPrinter->prettyPrint($stmts);
 
     echo $code;
-} catch (PhpParser\Error $e) {
-    echo 'Parse Error: ', $e->getMessage();
+} catch (Error $e) {
+    echo 'Parse Error: ', $e->getMessage(), "\n";
 }
 ```
 
 The above code will output:
 
-    <?php echo 'Hello ', hi\getTarget();
+    echo 'Hello ', hi\getTarget();
 
-As you can see the source code was first parsed using `PhpParser\Parser->parse()`, then changed and then
+As you can see, the source code was first parsed using `PhpParser\Parser->parse()`, then changed and then
 again converted to code using `PhpParser\PrettyPrinter\Standard->prettyPrint()`.
 
 The `prettyPrint()` method pretty prints a statements array. It is also possible to pretty print only a
@@ -176,8 +263,13 @@ single expression using `prettyPrintExpr()`.
 The `prettyPrintFile()` method can be used to print an entire file. This will include the opening `<?php` tag
 and handle inline HTML as the first/last statement more gracefully.
 
-Node traversation
------------------
+There is also a pretty-printing mode which retains formatting for parts of the AST that have not
+been changed, which requires additional setup.
+
+> Read more: [Pretty printing documentation](component/Pretty_printing.markdown)
+
+Node traversal
+--------------
 
 The above pretty printing example used the fact that the source code was known and thus it was easy to
 write code that accesses a certain part of a node tree and changes it. Normally this is not the case.
@@ -188,11 +280,13 @@ For this purpose the parser provides a component for traversing and visiting the
 structure of a program using this `PhpParser\NodeTraverser` looks like this:
 
 ```php
-<?php
+use PhpParser\NodeTraverser;
+use PhpParser\ParserFactory;
+use PhpParser\PrettyPrinter;
 
-$parser        = new PhpParser\Parser(new PhpParser\Lexer\Emulative);
-$traverser     = new PhpParser\NodeTraverser;
-$prettyPrinter = new PhpParser\PrettyPrinter\Standard;
+$parser        = (new ParserFactory())->createForHostVersion();
+$traverser     = new NodeTraverser;
+$prettyPrinter = new PrettyPrinter\Standard;
 
 // add your visitor
 $traverser->addVisitor(new MyNodeVisitor);
@@ -218,11 +312,10 @@ try {
 The corresponding node visitor might look like this:
 
 ```php
-<?php
 use PhpParser\Node;
+use PhpParser\NodeVisitorAbstract;
 
-class MyNodeVisitor extends PhpParser\NodeVisitorAbstract
-{
+class MyNodeVisitor extends NodeVisitorAbstract {
     public function leaveNode(Node $node) {
         if ($node instanceof Node\Scalar\String_) {
             $node->value = 'foo';
@@ -236,13 +329,15 @@ The above node visitor would change all string literals in the program to `'foo'
 All visitors must implement the `PhpParser\NodeVisitor` interface, which defines the following four
 methods:
 
-    public function beforeTraverse(array $nodes);
-    public function enterNode(PhpParser\Node $node);
-    public function leaveNode(PhpParser\Node $node);
-    public function afterTraverse(array $nodes);
+```php
+public function beforeTraverse(array $nodes);
+public function enterNode(\PhpParser\Node $node);
+public function leaveNode(\PhpParser\Node $node);
+public function afterTraverse(array $nodes);
+```
 
 The `beforeTraverse()` method is called once before the traversal begins and is passed the nodes the
-traverser was called with. This method can be used for resetting values before traversation or
+traverser was called with. This method can be used for resetting values before traversal or
 preparing the tree for traversal.
 
 The `afterTraverse()` method is similar to the `beforeTraverse()` method, with the only difference that
@@ -254,22 +349,28 @@ i.e. before its subnodes are traversed, the latter when it is left.
 All four methods can either return the changed node or not return at all (i.e. `null`) in which
 case the current node is not changed.
 
-The `enterNode()` method can additionally return the value `NodeTraverser::DONT_TRAVERSE_CHILDREN`,
-which instructs the traverser to skip all children of the current node.
+The `enterNode()` method can additionally return the value `NodeVisitor::DONT_TRAVERSE_CHILDREN`,
+which instructs the traverser to skip all children of the current node. To furthermore prevent subsequent
+visitors from visiting the current node, `NodeVisitor::DONT_TRAVERSE_CURRENT_AND_CHILDREN` can be used instead.
 
-The `leaveNode()` method can additionally return the value `NodeTraverser::REMOVE_NODE`, in which
-case the current node will be removed from the parent array. Furthermove it is possible to return
-an array of nodes, which will be merged into the parent array at the offset of the current node.
-I.e. if in `array(A, B, C)` the node `B` should be replaced with `array(X, Y, Z)` the result will
-be `array(A, X, Y, Z, C)`.
+Both methods can additionally return the following values:
+
+ * `NodeVisitor::STOP_TRAVERSAL`, in which case no further nodes will be visited.
+ * `NodeVisitor::REMOVE_NODE`, in which case the current node will be removed from the parent array.
+ * `NodeVisitor::REPLACE_WITH_NULL`, in which case the current node will be replaced with `null`.
+ * An array of nodes, which will be merged into the parent array at the offset of the current node.
+   I.e. if in `array(A, B, C)` the node `B` should be replaced with `array(X, Y, Z)` the result will
+   be `array(A, X, Y, Z, C)`.
 
 Instead of manually implementing the `NodeVisitor` interface you can also extend the `NodeVisitorAbstract`
 class, which will define empty default implementations for all the above methods.
 
+> Read more: [Walking the AST](component/Walking_the_AST.markdown)
+
 The NameResolver node visitor
 -----------------------------
 
-One visitor is already bundled with the package: `PhpParser\NodeVisitor\NameResolver`. This visitor
+One visitor that is already bundled with the package is `PhpParser\NodeVisitor\NameResolver`. This visitor
 helps you work with namespaced code by trying to resolve most names to fully qualified ones.
 
 For example, consider the following code:
@@ -280,18 +381,21 @@ For example, consider the following code:
 In order to know that `B\C` really is `A\C` you would need to track aliases and namespaces yourself.
 The `NameResolver` takes care of that and resolves names as far as possible.
 
-After running it most names will be fully qualified. The only names that will stay unqualified are
+After running it, most names will be fully qualified. The only names that will stay unqualified are
 unqualified function and constant names. These are resolved at runtime and thus the visitor can't
 know which function they are referring to. In most cases this is a non-issue as the global functions
 are meant.
 
-Also the `NameResolver` adds a `namespacedName` subnode to class, function and constant declarations
-that contains the namespaced name instead of only the shortname that is available via `name`.
+Additionally, the `NameResolver` adds a `namespacedName` subnode to class, function and constant
+declarations that contains the namespaced name instead of only the shortname that is available via
+`name`.
+
+> Read more: [Name resolution documentation](component/Name_resolution.markdown)
 
 Example: Converting namespaced code to pseudo namespaces
 --------------------------------------------------------
 
-A small example to understand the concept: We want to convert namespaced code to pseudo namespaces
+A small example to understand the concept: We want to convert namespaced code to pseudo namespaces,
 so it works on 5.2, i.e. names like `A\\B` should be converted to `A_B`. Note that such conversions
 are fairly complicated if you take PHP's dynamic features into account, so our conversion will
 assume that no dynamic features are used.
@@ -299,25 +403,29 @@ assume that no dynamic features are used.
 We start off with the following base code:
 
 ```php
-<?php
+use PhpParser\ParserFactory;
+use PhpParser\PrettyPrinter;
+use PhpParser\NodeTraverser;
+use PhpParser\NodeVisitor\NameResolver;
+
 $inDir  = '/some/path';
 $outDir = '/some/other/path';
 
-$parser        = new PhpParser\Parser(new PhpParser\Lexer\Emulative);
-$traverser     = new PhpParser\NodeTraverser;
-$prettyPrinter = new PhpParser\PrettyPrinter\Standard;
+$parser        = (new ParserFactory())->createForNewestSupportedVersion();
+$traverser     = new NodeTraverser;
+$prettyPrinter = new PrettyPrinter\Standard;
 
-$traverser->addVisitor(new PhpParser\NodeVisitor\NameResolver); // we will need resolved names
-$traverser->addVisitor(new NodeVisitor\NamespaceConverter);     // our own node visitor
+$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$/');
+$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);
+        $code = file_get_contents($file->getPathName());
 
         // parse
         $stmts = $parser->parse($code);
@@ -339,17 +447,17 @@ foreach ($files as $file) {
 }
 ```
 
-Now lets start with the main code, the `NodeVisitor\NamespaceConverter`. One thing it needs to do
+Now lets start with the main code, the `NamespaceConverter`. One thing it needs to do
 is convert `A\\B` style names to `A_B` style ones.
 
 ```php
-<?php
 use PhpParser\Node;
-class NodeVisitor_NamespaceConverter extends PhpParser\NodeVisitorAbstract
+
+class NamespaceConverter extends \PhpParser\NodeVisitorAbstract
 {
     public function leaveNode(Node $node) {
         if ($node instanceof Node\Name) {
-            return new Node\Name($node->toString('_'));
+            return new Node\Name(str_replace('\\', '_', $node->toString()));
         }
     }
 }
@@ -357,30 +465,30 @@ class NodeVisitor_NamespaceConverter extends PhpParser\NodeVisitorAbstract
 
 The above code profits from the fact that the `NameResolver` already resolved all names as far as
 possible, so we don't need to do that. We only need to create a string with the name parts separated
-by underscores instead of backslashes. This is what `$node->toString('_')` does. (If you want to
+by underscores instead of backslashes. This is what `str_replace('\\', '_', $node->toString())` does. (If you want to
 create a name with backslashes either write `$node->toString()` or `(string) $node`.) Then we create
 a new name from the string and return it. Returning a new node replaces the old node.
 
 Another thing we need to do is change the class/function/const declarations. Currently they contain
-only the shortname (i.e. the last part of the name), but they need to contain the complete name inclduing
+only the shortname (i.e. the last part of the name), but they need to contain the complete name including
 the namespace prefix:
 
 ```php
-<?php
 use PhpParser\Node;
 use PhpParser\Node\Stmt;
-class NodeVisitor_NamespaceConverter extends PhpParser\NodeVisitorAbstract
+
+class NodeVisitor_NamespaceConverter extends \PhpParser\NodeVisitorAbstract
 {
     public function leaveNode(Node $node) {
         if ($node instanceof Node\Name) {
-            return new Node\Name($node->toString('_'));
+            return new Node\Name(str_replace('\\', '_', $node->toString()));
         } elseif ($node instanceof Stmt\Class_
                   || $node instanceof Stmt\Interface_
                   || $node instanceof Stmt\Function_) {
-            $node->name = $node->namespacedName->toString('_');
+            $node->name = str_replace('\\', '_', $node->namespacedName->toString());
         } elseif ($node instanceof Stmt\Const_) {
             foreach ($node->consts as $const) {
-                $const->name = $const->namespacedName->toString('_');
+                $const->name = str_replace('\\', '_', $const->namespacedName->toString());
             }
         }
     }
@@ -392,28 +500,29 @@ There is not much more to it than converting the namespaced name to string with
 The last thing we need to do is remove the `namespace` and `use` statements:
 
 ```php
-<?php
 use PhpParser\Node;
 use PhpParser\Node\Stmt;
-class NodeVisitor_NamespaceConverter extends PhpParser\NodeVisitorAbstract
+use PhpParser\NodeVisitor;
+
+class NodeVisitor_NamespaceConverter extends \PhpParser\NodeVisitorAbstract
 {
     public function leaveNode(Node $node) {
         if ($node instanceof Node\Name) {
-            return new Node\Name($node->toString('_'));
+            return new Node\Name(str_replace('\\', '_', $node->toString()));
         } elseif ($node instanceof Stmt\Class_
                   || $node instanceof Stmt\Interface_
                   || $node instanceof Stmt\Function_) {
-            $node->name = $node->namespacedName->toString('_');
+            $node->name = str_replace('\\', '_', $node->namespacedName->toString();
         } elseif ($node instanceof Stmt\Const_) {
             foreach ($node->consts as $const) {
-                $const->name = $const->namespacedName->toString('_');
+                $const->name = str_replace('\\', '_', $const->namespacedName->toString());
             }
         } elseif ($node instanceof Stmt\Namespace_) {
             // returning an array merges is into the parent array
             return $node->stmts;
         } elseif ($node instanceof Stmt\Use_) {
-            // returning false removed the node altogether
-            return false;
+            // remove use nodes altogether
+            return NodeVisitor::REMOVE_NODE;
         }
     }
 }

doc/3_Other_node_tree_representations.markdown

@@ -1,203 +0,0 @@
-Other node tree representations
-===============================
-
-It is possible to convert the AST into several textual representations, which serve different uses.
-
-Simple serialization
---------------------
-
-It is possible to serialize the node tree using `serialize()` and also unserialize it using
-`unserialize()`. The output is not human readable and not easily processable from anything
-but PHP, but it is compact and generates fast. The main application thus is in caching.
-
-Human readable dumping
-----------------------
-
-Furthermore it is possible to dump nodes into a human readable format using the `dump` method of
-`PhpParser\NodeDumper`. This can be used for debugging.
-
-```php
-<?php
-$code = <<<'CODE'
-<?php
-
-function printLine($msg) {
-    echo $msg, "\n";
-}
-
-printLine('Hello World!!!');
-CODE;
-
-$parser = new PhpParser\Parser(new PhpParser\Lexer);
-$nodeDumper = new PhpParser\NodeDumper;
-
-try {
-    $stmts = $parser->parse($code);
-
-    echo $nodeDumper->dump($stmts), "\n";
-} catch (PhpParser\Error $e) {
-    echo 'Parse Error: ', $e->getMessage();
-}
-```
-
-The above script will have an output looking roughly like this:
-
-```
-array(
-    0: Stmt_Function(
-        byRef: false
-        params: array(
-            0: Param(
-                name: msg
-                default: null
-                type: null
-                byRef: false
-            )
-        )
-        stmts: array(
-            0: Stmt_Echo(
-                exprs: array(
-                    0: Expr_Variable(
-                        name: msg
-                    )
-                    1: Scalar_String(
-                        value:
-
-                    )
-                )
-            )
-        )
-        name: printLine
-    )
-    1: Expr_FuncCall(
-        name: Name(
-            parts: array(
-                0: printLine
-            )
-        )
-        args: array(
-            0: Arg(
-                value: Scalar_String(
-                    value: Hello World!!!
-                )
-                byRef: false
-            )
-        )
-    )
-)
-```
-
-Serialization to XML
---------------------
-
-It is also possible to serialize the node tree to XML using `PhpParser\Serializer\XML->serialize()`
-and to unserialize it using `PhpParser\Unserializer\XML->unserialize()`. This is useful for
-interfacing with other languages and applications or for doing transformation using XSLT.
-
-```php
-<?php
-$code = <<<'CODE'
-<?php
-
-function printLine($msg) {
-    echo $msg, "\n";
-}
-
-printLine('Hello World!!!');
-CODE;
-
-$parser = new PhpParser\Parser(new PhpParser\Lexer);
-$serializer = new PhpParser\Serializer\XML;
-
-try {
-    $stmts = $parser->parse($code);
-
-    echo $serializer->serialize($stmts);
-} catch (PhpParser\Error $e) {
-    echo 'Parse Error: ', $e->getMessage();
-}
-```
-
-Produces:
-
-```xml
-<?xml version="1.0" encoding="UTF-8"?>
-<AST xmlns:node="http://nikic.github.com/PHPParser/XML/node" xmlns:subNode="http://nikic.github.com/PHPParser/XML/subNode" xmlns:scalar="http://nikic.github.com/PHPParser/XML/scalar">
- <scalar:array>
-  <node:Stmt_Function line="2">
-   <subNode:byRef>
-    <scalar:false/>
-   </subNode:byRef>
-   <subNode:params>
-    <scalar:array>
-     <node:Param line="2">
-      <subNode:name>
-       <scalar:string>msg</scalar:string>
-      </subNode:name>
-      <subNode:default>
-       <scalar:null/>
-      </subNode:default>
-      <subNode:type>
-       <scalar:null/>
-      </subNode:type>
-      <subNode:byRef>
-       <scalar:false/>
-      </subNode:byRef>
-     </node:Param>
-    </scalar:array>
-   </subNode:params>
-   <subNode:stmts>
-    <scalar:array>
-     <node:Stmt_Echo line="3">
-      <subNode:exprs>
-       <scalar:array>
-        <node:Expr_Variable line="3">
-         <subNode:name>
-          <scalar:string>msg</scalar:string>
-         </subNode:name>
-        </node:Expr_Variable>
-        <node:Scalar_String line="3">
-         <subNode:value>
-          <scalar:string>
-</scalar:string>
-         </subNode:value>
-        </node:Scalar_String>
-       </scalar:array>
-      </subNode:exprs>
-     </node:Stmt_Echo>
-    </scalar:array>
-   </subNode:stmts>
-   <subNode:name>
-    <scalar:string>printLine</scalar:string>
-   </subNode:name>
-  </node:Stmt_Function>
-  <node:Expr_FuncCall line="6">
-   <subNode:name>
-    <node:Name line="6">
-     <subNode:parts>
-      <scalar:array>
-       <scalar:string>printLine</scalar:string>
-      </scalar:array>
-     </subNode:parts>
-    </node:Name>
-   </subNode:name>
-   <subNode:args>
-    <scalar:array>
-     <node:Arg line="6">
-      <subNode:value>
-       <node:Scalar_String line="6">
-        <subNode:value>
-         <scalar:string>Hello World!!!</scalar:string>
-        </subNode:value>
-       </node:Scalar_String>
-      </subNode:value>
-      <subNode:byRef>
-       <scalar:false/>
-      </subNode:byRef>
-     </node:Arg>
-    </scalar:array>
-   </subNode:args>
-  </node:Expr_FuncCall>
- </scalar:array>
-</AST>
-```

doc/4_Code_generation.markdown

@@ -1,80 +0,0 @@
-Code generation
-===============
-
-It is also possible to generate code using the parser, by first creating an Abstract Syntax Tree and then using the
-pretty printer to convert it to PHP code. To simplify code generation, the project comes with builders which allow
-creating node trees using a fluid interface, instead of instantiating all nodes manually. Builders are available for
-the following syntactic elements:
-
- * namespaces and use statements
- * classes, interfaces and traits
- * methods, functions and parameters
- * properties
-
-Here is an example:
-
-```php
-<?php
-$factory = new PhpParser\BuilderFactory;
-$node = $factory->namespace('Name\Space')
-    ->addStmt($factory->use('Some\Other\Thingy')->as('SomeOtherClass'))
-    ->addStmt($factory->class('SomeClass')
-        ->extend('SomeOtherClass')
-        ->implement('A\Few', '\Interfaces')
-        ->makeAbstract() // ->makeFinal()
-
-        ->addStmt($factory->method('someMethod')
-            ->makePublic()
-            ->makeAbstract() // ->makeFinal()
-            ->addParam($factory->param('someParam')->setTypeHint('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 PhpParser\Node\Expr\Print_(new PhpParser\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 PhpParser\PrettyPrinter\Standard();
-echo $prettyPrinter->prettyPrintFile($stmts);
-```
-
-This will produce the following output with the standard pretty printer:
-
-```php
-<?php
-
-namespace Name\Space;
-
-use Some\Other\Thingy as SomeClass;
-abstract class SomeClass extends SomeOtherClass implements A\Few, \Interfaces
-{
-    protected $someProperty;
-    private $anotherProperty = array(1, 2, 3);
-    /**
-     * This method does something.
-     *
-     * @param SomeClass And takes a parameter
-     */
-    public abstract function someMethod(SomeClass $someParam);
-    protected function anotherMethod($someParam = 'test')
-    {
-        print $someParam;
-    }
-}
-```

doc/README.md

@@ -0,0 +1,45 @@
+Table of Contents
+=================
+
+Guide
+-----
+
+  1. [Introduction](0_Introduction.markdown)
+  2. [Usage of basic components](2_Usage_of_basic_components.markdown)
+
+Component documentation
+-----------------------
+
+  * [Walking the AST](component/Walking_the_AST.markdown)
+    * Node visitors
+    * Modifying the AST from a visitor
+    * Short-circuiting traversals
+    * Interleaved visitors
+    * Simple node finding API
+    * Parent and sibling references
+  * [Name resolution](component/Name_resolution.markdown)
+    * Name resolver options
+    * Name resolution context
+  * [Pretty printing](component/Pretty_printing.markdown)
+    * Converting AST back to PHP code
+    * Customizing formatting
+    * Formatting-preserving code transformations
+  * [AST builders](component/AST_builders.markdown)
+    * Fluent builders for AST nodes
+  * [Lexer](component/Lexer.markdown)
+    * Emulation
+    * Tokens, positions and attributes
+  * [Error handling](component/Error_handling.markdown)
+    * Column information for errors
+    * Error recovery (parsing of syntactically incorrect code)
+  * [Constant expression evaluation](component/Constant_expression_evaluation.markdown)
+    * Evaluating constant/property/etc initializers
+    * Handling errors and unsupported expressions
+  * [JSON representation](component/JSON_representation.markdown)
+    * JSON encoding and decoding of ASTs
+  * [Performance](component/Performance.markdown)
+    * Disabling Xdebug
+    * Reusing objects
+    * Garbage collection impact
+  * [Frequently asked questions](component/FAQ.markdown)
+    * Parent and sibling references

doc/component/AST_builders.markdown

@@ -0,0 +1,141 @@
+AST builders
+============
+
+When PHP-Parser is used to generate (or modify) code by first creating an Abstract Syntax Tree and
+then using the [pretty printer](Pretty_printing.markdown) to convert it to PHP code, it can often
+be tedious to manually construct AST nodes. The project provides a number of utilities to simplify
+the construction of common AST nodes.
+
+Fluent builders
+---------------
+
+The library comes with a number of builders, which allow creating node trees using a fluent
+interface. Builders are created using the `BuilderFactory` and the final constructed node is
+accessed through `getNode()`. Fluent builders are available for
+the following syntactic elements:
+
+ * namespaces and use statements
+ * classes, interfaces, traits and enums
+ * methods, functions and parameters
+ * properties, class constants and enum cases
+ * trait uses and trait use adaptations
+
+Here is an example:
+
+```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);
+```
+
+This will produce the following output with the standard pretty printer:
+
+```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;
+    }
+}
+```
+
+Additional helper methods
+-------------------------
+
+The `BuilderFactory` also provides a number of additional helper methods, which directly return
+nodes. The following methods are currently available:
+
+ * `val($value)`: Creates an AST node for a literal value like `42` or `[1, 2, 3]`.
+ * `var($name)`: Creates variable node.
+ * `args(array $args)`: Creates an array of function/method arguments, including the required `Arg`
+   wrappers. Also converts literals to AST nodes.
+ * `funcCall($name, array $args = [])`: Create a function call node. Converts `$name` to a `Name`
+   node and normalizes arguments.
+ * `methodCall(Expr $var, $name, array $args = [])`: Create a method call node. Converts `$name` to
+   an `Identifier` node and normalizes arguments.
+ * `staticCall($class, $name, array $args = [])`: Create a static method call node. Converts
+   `$class` to a `Name` node, `$name` to an `Identifier` node and normalizes arguments.
+ * `new($class, array $args = [])`: Create a "new" (object creation) node. Converts `$class` to a
+   `Name` node.
+ * `constFetch($name)`: Create a constant fetch node. Converts `$name` to a `Name` node.
+ * `classConstFetch($class, $name)`: Create a class constant fetch node. Converts `$class` to a
+   `Name` node and `$name` to an `Identifier` node.
+ * `propertyFetch($var, $name)`: Creates a property fetch node. Converts `$name` to an `Identifier`
+   node.
+ * `concat(...$exprs)`: Create a tree of `BinaryOp\Concat` nodes for the given expressions.
+ * `attribute($name, $args)`: Create a `Attribute` node. Converts `$name` to a `Name` node and
+   normalizes arguments.
+
+These methods may be expanded on an as-needed basis. Please open an issue or PR if a common
+operation is missing.

doc/component/Constant_expression_evaluation.markdown

@@ -0,0 +1,117 @@
+Constant expression evaluation
+==============================
+
+Initializers for constants, properties, parameters, etc. have limited support for expressions. For
+example:
+
+```php
+<?php
+class Test {
+    const SECONDS_IN_HOUR = 60 * 60;
+    const SECONDS_IN_DAY = 24 * self::SECONDS_IN_HOUR;
+}
+```
+
+PHP-Parser supports evaluation of such constant expressions through the `ConstExprEvaluator` class:
+
+```php
+<?php
+
+use PhpParser\{ConstExprEvaluator, ConstExprEvaluationException};
+
+$evaluator = new ConstExprEvaluator();
+try {
+    $value = $evaluator->evaluateSilently($someExpr);
+} catch (ConstExprEvaluationException $e) {
+    // Either the expression contains unsupported expression types,
+    // or an error occurred during evaluation
+}
+```
+
+Error handling
+--------------
+
+The constant evaluator provides two methods, `evaluateDirectly()` and `evaluateSilently()`, which
+differ in error behavior. `evaluateDirectly()` will evaluate the expression as PHP would, including
+any generated warnings or Errors. `evaluateSilently()` will instead convert warnings and Errors into
+a `ConstExprEvaluationException`. For example:
+
+```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
+}
+```
+
+For the purposes of static analysis, you will likely want to use `evaluateSilently()` and leave
+erroring expressions unevaluated.
+
+Unsupported expressions and evaluator fallback
+----------------------------------------------
+
+The constant expression evaluator supports all expression types that are permitted in constant
+expressions, apart from the following:
+
+ * `Scalar\MagicConst\*`
+ * `Expr\ConstFetch` (only null/false/true are handled)
+ * `Expr\ClassConstFetch`
+ * `Expr\New_` (since PHP 8.1)
+ * `Expr\PropertyFetch` (since PHP 8.2)
+
+Handling these expression types requires non-local information, such as which global constants are
+defined. By default, the evaluator will throw a `ConstExprEvaluationException` when it encounters
+an unsupported expression type.
+
+It is possible to override this behavior and support resolution for these expression types by
+specifying an evaluation fallback function:
+
+```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
+}
+```
+
+Implementers are advised to ensure that evaluation of indirect constant references cannot lead to
+infinite recursion. For example, the following code could lead to infinite recursion if constant
+lookup is implemented naively.
+
+```php
+<?php
+class Test {
+    const A = self::B;
+    const B = self::A;
+}
+```

doc/component/Error.markdown

@@ -1,77 +0,0 @@
-Error handling
-==============
-
-Errors during parsing or analysis are represented using the `PhpParser\Error` exception class. In addition to an error
-message, an error can also store additional information about the location the error occurred at.
-
-How much location information is available depends on the origin of the error and how many lexer attributes have been
-enabled. At a minimum the start line of the error is usually available.
-
-Column information
-------------------
-
-In order to receive information about not only the line, but also the column span an error occurred at, the file
-position attributes in the lexer need to be enabled:
-
-```php
-$lexer = new PhpParser\Lexer(array(
-    'usedAttributes' => array('comments', 'startLine', 'endLine', 'startFilePos', 'endFilePos'),
-));
-$parser = new PhpParser\Parser($lexer);
-
-try {
-    $stmts = $parser->parse($code);
-    // ...
-} catch (PhpParser\Error $e) {
-    // ...
-}
-```
-
-Before using column information its availability needs to be checked with `$e->hasColumnInfo()`, as the precise
-location of an error cannot always be determined. The methods for retrieving column information also have to be passed
-the source code of the parsed file. An example for printing an error:
-
-```php
-if ($e->hasColumnInfo()) {
-    echo $e->getRawMessage() . ' from ' . $e->getStartLine() . ':' . $e->getStartColumn($code)
-        . ' to ' . $e->getEndLine() . ':' . $e->getEndColumn($code);
-} else {
-    echo $e->getMessage();
-}
-```
-
-Both line numbers and column numbers are 1-based. EOF errors will be located at the position one past the end of the
-file.
-
-Error recovery
---------------
-
-> **EXPERIMENTAL**
-
-By default the parser will throw an exception upon encountering the first error during parsing. An alternative mode is
-also supported, in which the parser will remember the error, but try to continue parsing the rest of the source code.
-
-To enable this mode the `throwOnError` parser option needs to be disabled. Any errors that occurred during parsing can
-then be retrieved using `$parser->getErrors()`. The `$parser->parse()` method will either return a partial syntax tree
-or `null` if recovery fails.
-
-A usage example:
-
-```php
-$parser = new PhpParser\Parser(new PhpParser\Lexer, array(
-    'throwOnError' => false,
-));
-
-$stmts = $parser->parse($code);
-$errors = $parser->getErrors();
-
-foreach ($errors as $error) {
-    // $error is an ordinary PhpParser\Error
-}
-
-if (null !== $stmts) {
-    // $stmts is a best-effort partial AST
-}
-```
-
-The error recovery implementation is experimental -- it currently won't be able to recover from many types of errors.

doc/component/Error_handling.markdown

@@ -0,0 +1,60 @@
+Error handling
+==============
+
+Errors during parsing or analysis are represented using the `PhpParser\Error` exception class. In addition to an error
+message, an error can also store additional information about the location the error occurred at.
+
+How much location information is available depends on the origin of the error. At a minimum the start line of the error
+is usually available.
+
+Column information
+------------------
+
+Before using column information, its availability needs to be checked with `$e->hasColumnInfo()`, as the precise
+location of an error cannot always be determined. The methods for retrieving column information also have to be passed
+the source code of the parsed file. An example for printing an error:
+
+```php
+if ($e->hasColumnInfo()) {
+    echo $e->getRawMessage() . ' from ' . $e->getStartLine() . ':' . $e->getStartColumn($code)
+        . ' to ' . $e->getEndLine() . ':' . $e->getEndColumn($code);
+    // or:
+    echo $e->getMessageWithColumnInfo($code);
+} else {
+    echo $e->getMessage();
+}
+```
+
+Both line numbers and column numbers are 1-based. EOF errors will be located at the position one past the end of the
+file.
+
+Error recovery
+--------------
+
+The error behavior of the parser (and other components) is controlled by an `ErrorHandler`. Whenever an error is
+encountered, `ErrorHandler::handleError()` is invoked. The default error handling strategy is `ErrorHandler\Throwing`,
+which will immediately throw when an error is encountered.
+
+To instead collect all encountered errors into an array, while trying to continue parsing the rest of the source code,
+an instance of `ErrorHandler\Collecting` can be passed to the `Parser::parse()` method. A usage example:
+
+```php
+$parser = (new PhpParser\ParserFactory())->createForHostVersion();
+$errorHandler = new PhpParser\ErrorHandler\Collecting;
+
+$stmts = $parser->parse($code, $errorHandler);
+
+if ($errorHandler->hasErrors()) {
+    foreach ($errorHandler->getErrors() as $error) {
+        // $error is an ordinary PhpParser\Error
+    }
+}
+
+if (null !== $stmts) {
+    // $stmts is a best-effort partial AST
+}
+```
+
+The partial AST may contain `Expr\Error` nodes that indicate that an error occurred while parsing an expression.
+
+The `NameResolver` visitor also accepts an `ErrorHandler` as a constructor argument.

doc/component/FAQ.markdown

@@ -0,0 +1,53 @@
+Frequently Asked Questions
+==========================
+
+ * [How can the parent of a node be obtained?](#how-can-the-parent-of-a-node-be-obtained)
+ * [How can the next/previous sibling of a node be obtained?](#how-can-the-nextprevious-sibling-of-a-node-be-obtained)
+
+How can the parent of a node be obtained?
+-----
+
+The AST does not store parent nodes by default. However, the `ParentConnectingVisitor` can be used to achieve this:
+
+```php
+use PhpParser\NodeTraverser;
+use PhpParser\NodeVisitor\ParentConnectingVisitor;
+use PhpParser\ParserFactory;
+
+$code = '...';
+
+$traverser = new NodeTraverser(new ParentConnectingVisitor);
+
+$parser = (new ParserFactory())->createForHostVersion();
+$ast    = $parser->parse($code);
+$ast    = $traverser->traverse($ast);
+```
+
+After running this visitor, the parent node can be obtained through `$node->getAttribute('parent')`.
+
+How can the next/previous sibling of a node be obtained?
+-----
+
+Again, siblings are not stored by default, but the `NodeConnectingVisitor` can be used to store
+the previous / next node with a common parent as well:
+
+```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);
+```
+
+After running this visitor, the parent node can be obtained through `$node->getAttribute('parent')`,
+the previous node can be obtained through `$node->getAttribute('previous')`, and the next node can be
+obtained through `$node->getAttribute('next')`.
+
+`ParentConnectingVisitor` and `NodeConnectingVisitor` should not be used at the same time. The latter
+includes the functionality of the former.

doc/component/JSON_representation.markdown

@@ -0,0 +1,139 @@
+JSON representation
+===================
+
+Nodes (and comments) implement the `JsonSerializable` interface. As such, it is possible to JSON
+encode the AST directly using `json_encode()`:
+
+```php
+<?php
+
+use PhpParser\ParserFactory;
+
+$code = <<<'CODE'
+<?php
+
+/** @param string $msg */
+function printLine($msg) {
+    echo $msg, "\n";
+}
+CODE;
+
+$parser = (new ParserFactory())->createForHostVersion();
+
+try {
+    $stmts = $parser->parse($code);
+
+    echo json_encode($stmts, JSON_PRETTY_PRINT), "\n";
+} catch (PhpParser\Error $e) {
+    echo 'Parse Error: ', $e->getMessage();
+}
+```
+
+This will result in the following output (which includes attributes):
+
+```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
+    }
+]
+```
+
+The JSON representation may be converted back into an AST using the `JsonDecoder`:
+
+```php
+<?php
+
+$jsonDecoder = new PhpParser\JsonDecoder();
+$ast = $jsonDecoder->decode($json);
+```
+
+Note that not all ASTs can be represented using JSON. In particular:
+
+ * JSON only supports UTF-8 strings.
+ * JSON does not support non-finite floating-point numbers. This can occur if the original source
+   code contains non-representable floating-pointing literals such as `1e1000`.
+
+If the node tree is not representable in JSON, the initial `json_encode()` call will fail.
+
+From the command line, a JSON dump can be obtained using `vendor/bin/php-parse -j file.php`.

doc/component/Lexer.markdown

@@ -1,52 +1,96 @@
 Lexer component documentation
 =============================
 
-The lexer is responsible for providing tokens to the parser. The project comes with two lexers: `PhpParser\Lexer` and
-`PhpParser\Lexer\Emulative`. The latter is an extension of the former, which adds the ability to emulate tokens of
-newer PHP versions and thus allows parsing of new code on older versions.
+The lexer is responsible for providing tokens to the parser. Typical use of the library does not require direct
+interaction with the lexer, as an appropriate lexer is created by `PhpParser\ParserFactory`. The tokens produced
+by the lexer can then be retrieved using `PhpParser\Parser::getTokens()`.
 
-This documentation discusses options available for the default lexers and explains how lexers can be extended.
+Emulation
+---------
 
-Lexer options
--------------
+While this library implements a custom parser, it relies on PHP's `ext/tokenizer` extension to perform lexing. However,
+this extension only supports lexing code for the PHP version you are running on, while this library also wants to support
+parsing newer code. For that reason, the lexer performs additional "emulation" in three layers:
 
-The two default lexers accept an `$options` array in the constructor. Currently only the `'usedAttributes'` option is
-supported, which allows you to specify which attributes will be added to the AST nodes. The attributes can then be
-accessed using `$node->getAttribute()`, `$node->setAttribute()`, `$node->hasAttribute()` and `$node->getAttributes()`
-methods. A sample options array:
+First, PhpParser uses the `PhpToken` based representation introduced in PHP 8.0, rather than the array-based tokens from
+previous versions. The `PhpParser\Token` class either extends `PhpToken` (on PHP 8.0) or a polyfill implementation. The
+polyfill implementation will also perform two emulations that are required by the parser and cannot be disabled:
+
+ * Single-line comments use the PHP 8.0 representation that does not include a trailing newline. The newline will be
+   part of a following `T_WHITESPACE` token.
+ * Namespaced names use the PHP 8.0 representation using `T_NAME_FULLY_QUALIFIED`, `T_NAME_QUALIFIED` and
+   `T_NAME_RELATIVE` tokens, rather than the previous representation using a sequence of `T_STRING` and `T_NS_SEPARATOR`.
+   This means that certain code that is legal on older versions (namespaced names including whitespace, such as `A \ B`)
+   will not be accepted by the parser.
+
+Second, the `PhpParser\Lexer` base class will convert `&` tokens into the PHP 8.1 representation of either
+`T_AMPERSAND_FOLLOWED_BY_VAR_OR_VARARG` or `T_AMPERSAND_NOT_FOLLOWED_BY_VAR_OR_VARARG`. This is required by the parser
+and cannot be disabled.
+
+Finally, `PhpParser\Lexer\Emulative` performs other, optional emulations. This lexer is parameterized by `PhpVersion`
+and will try to emulate `ext/tokenizer` output for that version. This is done using separate `TokenEmulator`s for each
+emulated feature.
+
+Emulation is usually used to support newer PHP versions, but there is also very limited support for reverse emulation to
+older PHP versions, which can make keywords from newer versions non-reserved.
+
+Tokens, positions and attributes
+--------------------------------
+
+The `Lexer::tokenize()` method returns an array of `PhpParser\Token`s. The most important parts of the interface can be
+summarized as follows:
 
 ```php
-$lexer = new PhpParser\Lexer(array(
-    'usedAttributes' => array(
-        'comments', 'startLine', 'endLine'
-    )
-));
+class Token {
+    /** @var int Token ID, either T_* or ord($char) for single-character tokens. */
+    public int $id;
+    /** @var string The textual content of the token. */
+    public string $text;
+    /** @var int The 1-based starting line of the token (or -1 if unknown). */
+    public int $line;
+    /** @var int The 0-based starting position of the token (or -1 if unknown). */
+    public int $pos;
+
+    /** @param int|string|(int|string)[] $kind Token ID or text (or array of them) */
+    public function is($kind): bool;
+}
 ```
 
-The attributes used in this example match the default behavior of the lexer. The following attributes are supported:
+Unlike PHP's own `PhpToken::tokenize()` output, the token array is terminated by a sentinel token with ID 0.
 
- * `comments`: Array of `PhpParser\Comment` or `PhpParser\Comment\Doc` instances, representing all comments that occurred
-   between the previous non-discarded token and the current one. Use of this attribute is required for the
-   `$node->getDocComment()` method to work. The attribute is also needed if you wish the pretty printer to retain
-   comments present in the original code.
- * `startLine`: Line in which the node starts. This attribute is required for the `$node->getLine()` to work. It is also
-   required if syntax errors should contain line number information.
- * `endLine`: Line in which the node ends.
- * `startTokenPos`: Offset into the token array of the first token in the node.
- * `endTokenPos`: Offset into the token array of the last token in the node.
- * `startFilePos`: Offset into the code string of the first character that is part of the node.
- * `endFilePos`: Offset into the code string of the last character that is part of the node.
+The lexer is normally invoked implicitly by the parser. In that case, the tokens for the last parse can be retrieved
+using `Parser::getTokens()`.
+
+Nodes in the AST produced by the parser always corresponds to some range of tokens. The parser adds a number of
+positioning attributes to allow mapping nodes back to lines, tokens or file offsets:
+
+ * `startLine`: Line in which the node starts. Used by `$node->getStartLine()`.
+ * `endLine`: Line in which the node ends. Used by `$node->getEndLine()`.
+ * `startTokenPos`: Offset into the token array of the first token in the node. Used by `$node->getStartTokenPos()`.
+ * `endTokenPos`: Offset into the token array of the last token in the node. Used by `$node->getEndTokenPos()`.
+ * `startFilePos`: Offset into the code string of the first character that is part of the node. Used by `$node->getStartFilePos()`.
+ * `endFilePos`: Offset into the code string of the last character that is part of the node. Used by `$node->getEndFilePos()`.
+
+Note that `start`/`end` here are closed rather than half-open ranges. This means that a node consisting of a single
+token will have `startTokenPos == endTokenPos` rather than `startTokenPos + 1 == endTokenPos`. This also means that a
+zero-length node will have `startTokenPos -1 == endTokenPos`.
 
 ### Using token positions
 
+> **Note:** The example in this section is outdated in that this information is directly available in the AST: While
+> `$property->isPublic()` does not distinguish between `public` and `var`, directly checking `$property->flags` for
+> the `$property->flags & Class_::VISIBILITY_MODIFIER_MASK) === 0` allows making this distinction without resorting to
+> tokens. However, the general idea behind the example still applies in other cases.
+
 The token offset information is useful if you wish to examine the exact formatting used for a node. For example the AST
 does not distinguish whether a property was declared using `public` or using `var`, but you can retrieve this
 information based on the token position:
 
 ```php
+/** @param PhpParser\Token[] $tokens */
 function isDeclaredUsingVar(array $tokens, PhpParser\Node\Stmt\Property $prop) {
-    $i = $prop->getAttribute('startTokenPos');
-    return $tokens[$i][0] === T_VAR;
+    $i = $prop->getStartTokenPos();
+    return $tokens[$i]->id === T_VAR;
 }
 ```
 
@@ -67,80 +111,16 @@ class MyNodeVisitor extends PhpParser\NodeVisitorAbstract {
     }
 }
 
-$lexer = new PhpParser\Lexer(array(
-    'usedAttributes' => array(
-        'comments', 'startLine', 'endLine', 'startTokenPos', 'endTokenPos'
-    )
-));
-$parser = new PhpParser\Parser($lexer);
+$parser = (new PhpParser\ParserFactory())->createForHostVersion($lexerOptions);
 
 $visitor = new MyNodeVisitor();
-$traverser = new PhpParser\NodeTraverser();
-$traverser->addVisitor($visitor);
+$traverser = new PhpParser\NodeTraverser($visitor);
 
 try {
     $stmts = $parser->parse($code);
-    $visitor->setTokens($lexer->getTokens());
+    $visitor->setTokens($parser->getTokens());
     $stmts = $traverser->traverse($stmts);
 } catch (PhpParser\Error $e) {
     echo 'Parse Error: ', $e->getMessage();
 }
 ```
-
-The same approach can also be used to perform specific modifications in the code, without changing the formatting in
-other places (which is the case when using the pretty printer).
-
-Lexer extension
----------------
-
-A lexer has to define the following public interface:
-
-    void startLexing(string $code);
-    array getTokens();
-    string handleHaltCompiler();
-    int getNextToken(string &$value = null, array &$startAttributes = null, array &$endAttributes = null);
-
-The `startLexing()` method is invoked with the source code that is to be lexed (including the opening tag) whenever the
-`parse()` method of the parser is called. It can be used to reset state or preprocess the source code or tokens.
-
-The `getTokens()` method returns the current token array, in the usual `token_get_all()` format. This method is not
-used by the parser (which uses `getNextToken()`), but is useful in combination with the token position attributes.
-
-The `handleHaltCompiler()` method is called whenever a `T_HALT_COMPILER` token is encountered. It has to return the
-remaining string after the construct (not including `();`).
-
-The `getNextToken()` method returns the ID of the next token (as defined by the `Parser::T_*` constants). If no more
-tokens are available it must return `0`, which is the ID of the `EOF` token. Furthermore the string content of the
-token should be written into the by-reference `$value` parameter (which will then be available as `$n` in the parser).
-
-### Attribute handling
-
-The other two by-ref variables `$startAttributes` and `$endAttributes` define which attributes will eventually be
-assigned to the generated nodes: The parser will take the `$startAttributes` from the first token which is part of the
-node and the `$endAttributes` from the last token that is part of the node.
-
-E.g. if the tokens `T_FUNCTION T_STRING ... '{' ... '}'` constitute a node, then the `$startAttributes` from the
-`T_FUNCTION` token will be taken and the `$endAttributes` from the `'}'` token.
-
-An application of custom attributes is storing the original formatting of literals: The parser does not retain
-information about the formatting of integers (like decimal vs. hexadecimal) or strings (like used quote type or used
-escape sequences). This can be remedied by storing the original value in an attribute:
-
-```php
-class KeepOriginalValueLexer extends PHPParser\Lexer // or PHPParser\Lexer\Emulative
-{
-    public function getNextToken(&$value = null, &$startAttributes = null, &$endAttributes = null) {
-        $tokenId = parent::getNextToken($value, $startAttributes, $endAttributes);
-
-        if ($tokenId == PHPParser\Parser::T_CONSTANT_ENCAPSED_STRING // non-interpolated string
-            || $tokenId == PHPParser\Parser::T_LNUMBER               // integer
-            || $tokenId == PHPParser\Parser::T_DNUMBER               // floating point number
-        ) {
-            // could also use $startAttributes, doesn't really matter here
-            $endAttributes['originalValue'] = $value;
-        }
-
-        return $tokenId;
-    }
-}
-```

doc/component/Name_resolution.markdown

@@ -0,0 +1,87 @@
+Name resolution
+===============
+
+Since the introduction of namespaces in PHP 5.3, literal names in PHP code are subject to a
+relatively complex name resolution process, which is based on the current namespace, the current
+import table state, as well the type of the referenced symbol. PHP-Parser implements name
+resolution and related functionality, both as reusable logic (NameContext), as well as a node
+visitor (NameResolver) based on it.
+
+The NameResolver visitor
+------------------------
+
+The `NameResolver` visitor can (and for nearly all uses of the AST, should) be applied to resolve names
+to their fully-qualified form, to the degree that this is possible.
+
+```php
+$nameResolver = new PhpParser\NodeVisitor\NameResolver;
+$nodeTraverser = new PhpParser\NodeTraverser;
+$nodeTraverser->addVisitor($nameResolver);
+
+// Resolve names
+$stmts = $nodeTraverser->traverse($stmts);
+```
+
+In the default configuration, the name resolver will perform three actions:
+
+ * Declarations of functions, classes, interfaces, traits, enums and global constants will have a
+   `namespacedName` property added, which contains the function/class/etc name including the
+   namespace prefix. For historic reasons this is a **property** rather than an attribute.
+ * Names will be replaced by fully qualified resolved names, which are instances of
+   `Node\Name\FullyQualified`.
+ * Unqualified function and constant names inside a namespace cannot be statically resolved. Inside
+   a namespace `Foo`, a call to `strlen()` may either refer to the namespaced `\Foo\strlen()`, or
+   the global `\strlen()`. Because PHP-Parser does not have the necessary context to decide this,
+   such names are left unresolved. Additionally, a `namespacedName` **attribute** is added to the
+   name node.
+
+The name resolver accepts an option array as the second argument, with the following default values:
+
+```php
+$nameResolver = new PhpParser\NodeVisitor\NameResolver(null, [
+    'preserveOriginalNames' => false,
+    'replaceNodes' => true,
+]);
+```
+
+If the `preserveOriginalNames` option is enabled, then the resolved (fully qualified) name will have
+an `originalName` attribute, which contains the unresolved name.
+
+If the `replaceNodes` option is disabled, then names will no longer be resolved in-place. Instead, a
+`resolvedName` attribute will be added to each name, which contains the resolved (fully qualified)
+name. Once again, if an unqualified function or constant name cannot be resolved, then the
+`resolvedName` attribute will not be present, and instead a `namespacedName` attribute is added.
+
+The `replaceNodes` attribute is useful if you wish to perform modifications on the AST, as you
+probably do not wish the resulting code to have fully resolved names as a side-effect.
+
+The NameContext
+---------------
+
+The actual name resolution logic is implemented in the `NameContext` class, which has the following
+public API:
+
+```php
+class NameContext {
+    public function __construct(ErrorHandler $errorHandler);
+    public function startNamespace(Name $namespace = null);
+    public function addAlias(Name $name, string $aliasName, int $type, array $errorAttrs = []);
+
+    public function getNamespace();
+    public function getResolvedName(Name $name, int $type);
+    public function getResolvedClassName(Name $name) : Name;
+    public function getPossibleNames(string $name, int $type) : array;
+    public function getShortName(string $name, int $type) : Name;
+}
+```
+
+The `$type` parameters accept one of the `Stmt\Use_::TYPE_*` constants, which represent the three
+basic symbol types in PHP (functions, constants and everything else).
+
+Next to name resolution, the `NameContext` also supports the reverse operation of finding a short
+representation of a name given the current name resolution environment.
+
+The name context is intended to be used for name resolution operations outside the AST itself, such
+as class names inside doc comments. A visitor running in parallel with the name resolver can access
+the name context using `$nameResolver->getNameContext()`. Alternatively a visitor can use an
+independent context and explicitly feed `Namespace` and `Use` nodes to it.

doc/component/Performance.markdown

@@ -0,0 +1,44 @@
+Performance
+===========
+
+Parsing is computationally expensive task, to which the PHP language is not very well suited.
+Nonetheless, there are a few things you can do to improve the performance of this library, which are
+described in the following.
+
+Xdebug
+------
+
+Running PHP with Xdebug adds a lot of overhead, especially for code that performs many method calls.
+Just by loading Xdebug (without enabling profiling or other more intrusive Xdebug features), you
+can expect that code using PHP-Parser will be approximately *five times slower*.
+
+As such, you should make sure that Xdebug is not loaded when using this library. Note that setting
+the `xdebug.default_enable=0` ini option does *not* disable Xdebug. The *only* way to disable
+Xdebug is to not load the extension in the first place.
+
+If you are building a command-line utility for use by developers (who often have Xdebug enabled),
+you may want to consider automatically restarting PHP with Xdebug unloaded. The
+[composer/xdebug-handler](https://github.com/composer/xdebug-handler) package can be used to do
+this.
+
+If you do run with Xdebug, you may need to increase the `xdebug.max_nesting_level` option to a
+higher level, such as 3000. While the parser itself is recursion free, most other code working on
+the AST uses recursion and will generate an error if the value of this option is too low.
+
+Assertions
+----------
+
+Assertions should be disabled in a production context by setting `zend.assertions=-1` (or
+`zend.assertions=0` if set at runtime). The library currently doesn't make heavy use of assertions,
+but they are used in an increasing number of places.
+
+Object reuse
+------------
+
+Many objects in this project are designed for reuse. For example, one `Parser` object can be used to
+parse multiple files.
+
+When possible, objects should be reused rather than being newly instantiated for every use. Some
+objects have expensive initialization procedures, which will be unnecessarily repeated if the object
+is not reused. (Currently two objects with particularly expensive setup are parsers and pretty
+printers, though the details might change between versions of this library.)

doc/component/Pretty_printing.markdown

@@ -0,0 +1,101 @@
+Pretty printing
+===============
+
+Pretty printing is the process of converting a syntax tree back to PHP code. In its basic mode of
+operation the pretty printer provided by this library will print the AST using a certain predefined
+code style and will discard (nearly) all formatting of the original code. Because programmers tend
+to be rather picky about their code formatting, this mode of operation is not very suitable for
+refactoring code, but can be used for automatically generated code, which is usually only read for
+debugging purposes.
+
+Basic usage
+-----------
+
+```php
+$stmts = $parser->parse($code);
+
+// MODIFY $stmts here
+
+$prettyPrinter = new PhpParser\PrettyPrinter\Standard;
+$newCode = $prettyPrinter->prettyPrintFile($stmts);
+```
+
+The pretty printer has three basic printing methods: `prettyPrint()`, `prettyPrintFile()` and
+`prettyPrintExpr()`. The one that is most commonly useful is `prettyPrintFile()`, which takes an
+array of statements and produces a full PHP file, including opening `<?php`.
+
+`prettyPrint()` also takes a statement array, but produces code which is valid inside an already
+open `<?php` context. Lastly, `prettyPrintExpr()` takes an `Expr` node and prints only a single
+expression.
+
+Customizing the formatting
+--------------------------
+
+The pretty printer respects a number of `kind` attributes used by some nodes (e.g., whether an
+integer should be printed as decimal, hexadecimal, etc). Additionally, it supports three options:
+
+* `phpVersion` (defaults to 7.4) allows opting into formatting that is not supported by older PHP
+  versions.
+* `newline` (defaults to `"\n"`) can be set to `"\r\n"` in order to produce Windows newlines.
+* `shortArraySyntax` determines the used array syntax if the `kind` attribute is not set. This is
+  a legacy option, and `phpVersion` should be used to control this behavior instead.
+
+The behaviors controlled by `phpVersion` (defaults to PHP 7.4) are:
+
+* For PHP >= 7.0, short array syntax `[]` will be used by default. This does not affect nodes that
+  specify an explicit array syntax using the `kind` attribute.
+* For PHP >= 7.0, parentheses around `yield` expressions will only be printed when necessary.
+* For PHP >= 7.1, the short array syntax `[]` will be used for destructuring by default (instead of
+  `list()`). This does not affect nodes that specify and explicit syntax using the `kind` attribute.
+* For PHP >= 7.3, a newline is no longer forced after heredoc/nowdoc strings, as the requirement
+  for this has been removed with the introduction of flexible heredoc/nowdoc strings.
+* For PHP >= 7.3, heredoc/nowdoc strings are indented just like regular code. This was allowed with
+  the introduction of flexible heredoc/nowdoc strings.
+
+The default pretty printer does not provide functionality for fine-grained customization of code
+formatting.
+
+If you want to make minor changes to the formatting, the easiest way is to extend the pretty printer
+and override the methods responsible for the node types you are interested in.
+
+If you want to have more fine-grained formatting control, the recommended method is to combine the
+default pretty printer with an existing library for code reformatting, such as
+[PHP-CS-Fixer](https://github.com/FriendsOfPHP/PHP-CS-Fixer).
+
+Formatting-preserving pretty printing
+-------------------------------------
+
+For automated code refactoring, migration and similar, you will usually only want to modify a small
+portion of the code and leave the remainder alone. The basic pretty printer is not suitable for
+this, because it will also reformat parts of the code which have not been modified.
+
+Since PHP-Parser 4.0, a formatting-preserving pretty-printing mode is available, which
+attempts to preserve the formatting of code (those AST nodes that have not changed) and only reformat
+code which has been modified or newly inserted.
+
+Use of the formatting-preservation functionality requires some additional preparatory steps:
+
+```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);
+```
+
+If you make use of the name resolution functionality, you will likely want to disable the
+`replaceNodes` option. This will add resolved names as attributes, instead of directly modifying
+the AST and causing spurious changes to the pretty printed code. For more information, see the
+[name resolution documentation](Name_resolution.markdown).
+
+The formatting-preservation works on a best-effort basis and may sometimes reformat more code than
+necessary. If you encounter problems while using this functionality, please open an issue.

doc/component/Walking_the_AST.markdown

@@ -0,0 +1,364 @@
+Walking the AST
+===============
+
+The most common way to work with the AST is by using a node traverser and one or more node visitors.
+As a basic example, the following code changes all literal integers in the AST into strings (e.g.,
+`42` becomes `'42'`.)
+
+```php
+use PhpParser\{Node, NodeTraverser, NodeVisitorAbstract};
+
+$traverser = new NodeTraverser;
+$traverser->addVisitor(new class extends NodeVisitorAbstract {
+    public function leaveNode(Node $node) {
+        if ($node instanceof Node\Scalar\Int_) {
+            return new Node\Scalar\String_((string) $node->value);
+        }
+    }
+});
+
+$stmts = ...;
+$modifiedStmts = $traverser->traverse($stmts);
+```
+
+Visitors can be either passed to the `NodeTraverser` constructor, or added using `addVisitor()`:
+
+```php
+$traverser = new NodeTraverser($visitor1, $visitor2, $visitor3);
+
+// Equivalent to:
+$traverser = new NodeTraverser();
+$traverser->addVisitor($visitor1);
+$traverser->addVisitor($visitor2);
+$traverser->addVisitor($visitor3);
+```
+
+Node visitors
+-------------
+
+Each node visitor implements an interface with following four methods:
+
+```php
+interface NodeVisitor {
+    public function beforeTraverse(array $nodes);
+    public function enterNode(Node $node);
+    public function leaveNode(Node $node);
+    public function afterTraverse(array $nodes);
+}
+```
+
+The `beforeTraverse()` and `afterTraverse()` methods are called before and after the traversal
+respectively, and are passed the entire AST. They can be used to perform any necessary state
+setup or cleanup.
+
+The `enterNode()` method is called when a node is first encountered, before its children are
+processed ("preorder"). The `leaveNode()` method is called after all children have been visited
+("postorder").
+
+For example, if we have the following excerpt of an AST
+
+```
+Expr_FuncCall(
+   name: Name(
+       name: printLine
+   )
+   args: array(
+       0: Arg(
+           name: null
+           value: Scalar_String(
+               value: Hello World!!!
+           )
+           byRef: false
+           unpack: false
+       )
+   )
+)
+```
+
+then the enter/leave methods will be called in the following order:
+
+```
+enterNode(Expr_FuncCall)
+enterNode(Name)
+leaveNode(Name)
+enterNode(Arg)
+enterNode(Scalar_String)
+leaveNode(Scalar_String)
+leaveNode(Arg)
+leaveNode(Expr_FuncCall)
+```
+
+A common pattern is that `enterNode` is used to collect some information and then `leaveNode`
+performs modifications based on that. At the time when `leaveNode` is called, all the code inside
+the node will have already been visited and necessary information collected.
+
+As you usually do not want to implement all four methods, it is recommended that you extend
+`NodeVisitorAbstract` instead of implementing the interface directly. The abstract class provides
+empty default implementations.
+
+Modifying the AST
+-----------------
+
+There are a number of ways in which the AST can be modified from inside a node visitor. The first
+and simplest is to simply change AST properties inside the visitor:
+
+```php
+public function leaveNode(Node $node) {
+    if ($node instanceof Node\Scalar\LNumber) {
+        // increment all integer literals
+        $node->value++;
+    }
+}
+```
+
+The second is to replace a node entirely by returning a new node:
+
+```php
+public function leaveNode(Node $node) {
+    if ($node instanceof Node\Expr\BinaryOp\BooleanAnd) {
+        // Convert all $a && $b expressions into !($a && $b)
+        return new Node\Expr\BooleanNot($node);
+    }
+}
+```
+
+Doing this is supported both inside enterNode and leaveNode. However, you have to be mindful about
+where you perform the replacement: If a node is replaced in enterNode, then the recursive traversal
+will also consider the children of the new node. If you aren't careful, this can lead to infinite
+recursion. For example, let's take the previous code sample and use enterNode instead:
+
+```php
+public function enterNode(Node $node) {
+    if ($node instanceof Node\Expr\BinaryOp\BooleanAnd) {
+        // Convert all $a && $b expressions into !($a && $b)
+        return new Node\Expr\BooleanNot($node);
+    }
+}
+```
+
+Now `$a && $b` will be replaced by `!($a && $b)`. Then the traverser will go into the first (and
+only) child of `!($a && $b)`, which is `$a && $b`. The transformation applies again and we end up
+with `!!($a && $b)`. This will continue until PHP hits the memory limit.
+
+Finally, there are three special replacement types. The first is removal of a node:
+
+```php
+public function leaveNode(Node $node) {
+    if ($node instanceof Node\Stmt\Return_) {
+        // Remove all return statements
+        return NodeVisitor::REMOVE_NODE;
+    }
+}
+```
+
+Node removal only works if the parent structure is an array. This means that usually it only makes
+sense to remove nodes of type `Node\Stmt`, as they always occur inside statement lists (and a few
+more node types like `Arg` or `Expr\ArrayItem`, which are also always part of lists).
+
+On the other hand, removing a `Node\Expr` does not make sense: If you have `$a * $b`, there is no
+meaningful way in which the `$a` part could be removed. If you want to remove an expression, you
+generally want to remove it together with a surrounding expression statement:
+
+```php
+public function leaveNode(Node $node) {
+    if ($node instanceof Node\Stmt\Expression
+        && $node->expr instanceof Node\Expr\FuncCall
+        && $node->expr->name instanceof Node\Name
+        && $node->expr->name->toString() === 'var_dump'
+    ) {
+        return NodeVisitor::REMOVE_NODE;
+    }
+}
+```
+
+This example will remove all calls to `var_dump()` which occur as expression statements. This means
+that `var_dump($a);` will be removed, but `if (var_dump($a))` will not be removed (and there is no
+obvious way in which it can be removed).
+
+Another way to remove nodes is to replace them with `null`. For example, all `else` statements could
+be removed as follows:
+
+```php
+public function leaveNode(Node $node) {
+    if ($node instanceof Node\Stmt\Else_) {
+        return NodeVisitor::REPLACE_WITH_NULL;
+    }
+}
+```
+
+This is only safe to do if the subnode the node is stored in is nullable. `Node\Stmt\Else_` only
+occurs inside `Node\Stmt\If_::$else`, which is nullable, so this particular replacement is safe.
+
+Next to removing nodes, it is also possible to replace one node with multiple nodes. This
+only works if the parent structure is an array.
+
+```php
+public function leaveNode(Node $node) {
+    if ($node instanceof Node\Stmt\Return_ && $node->expr !== null) {
+        // Convert "return foo();" into "$retval = foo(); return $retval;"
+        $var = new Node\Expr\Variable('retval');
+        return [
+            new Node\Stmt\Expression(new Node\Expr\Assign($var, $node->expr)),
+            new Node\Stmt\Return_($var),
+        ];
+    }
+}
+```
+
+Short-circuiting traversal
+--------------------------
+
+An AST can easily contain thousands of nodes, and traversing over all of them may be slow,
+especially if you have more than one visitor. In some cases, it is possible to avoid a full
+traversal.
+
+If you are looking for all class declarations in a file (and assuming you're not interested in
+anonymous classes), you know that once you've seen a class declaration, there is no point in also
+checking all it's child nodes, because PHP does not allow nesting classes. In this case, you can
+instruct the traverser to not recurse into the class node:
+
+```php
+private $classes = [];
+public function enterNode(Node $node) {
+    if ($node instanceof Node\Stmt\Class_) {
+        $this->classes[] = $node;
+        return NodeVisitor::DONT_TRAVERSE_CHILDREN;
+    }
+}
+```
+
+Of course, this option is only available in enterNode, because it's already too late by the time
+leaveNode is reached.
+
+If you are only looking for one specific node, it is also possible to abort the traversal entirely
+after finding it. For example, if you are looking for the node of a class with a certain name (and
+discounting exotic cases like conditionally defining a class two times), you can stop traversal
+once you found it:
+
+```php
+private $class = null;
+public function enterNode(Node $node) {
+    if ($node instanceof Node\Stmt\Class_ &&
+        $node->namespacedName->toString() === 'Foo\Bar\Baz'
+    ) {
+        $this->class = $node;
+        return NodeVisitor::STOP_TRAVERSAL;
+    }
+}
+```
+
+This works both in enterNode and leaveNode. Note that this particular case can also be more easily
+handled using a NodeFinder, which will be introduced below.
+
+Multiple visitors
+-----------------
+
+A single traverser can be used with multiple visitors:
+
+```php
+$traverser = new NodeTraverser;
+$traverser->addVisitor($visitorA);
+$traverser->addVisitor($visitorB);
+$stmts = $traverser->traverse($stmts);
+```
+
+It is important to understand that if a traverser is run with multiple visitors, the visitors will
+be interleaved. Given the following AST excerpt
+
+```
+Stmt_Return(
+    expr: Expr_Variable(
+        name: foobar
+    )
+)
+```
+
+the following method calls will be performed:
+
+```php
+$visitorA->enterNode(Stmt_Return)
+$visitorB->enterNode(Stmt_Return)
+$visitorA->enterNode(Expr_Variable)
+$visitorB->enterNode(Expr_Variable)
+$visitorB->leaveNode(Expr_Variable)
+$visitorA->leaveNode(Expr_Variable)
+$visitorB->leaveNode(Stmt_Return)
+$visitorA->leaveNode(Stmt_Return)
+```
+
+That is, when visiting a node, `enterNode()` and `leaveNode()` will always be called for all
+visitors, with the `leaveNode()` calls happening in the reverse order of the `enterNode()` calls.
+Running multiple visitors in parallel improves performance, as the AST only has to be traversed
+once. However, it is not always possible to write visitors in a way that allows interleaved
+execution. In this case, you can always fall back to performing multiple traversals:
+
+```php
+$traverserA = new NodeTraverser;
+$traverserA->addVisitor($visitorA);
+$traverserB = new NodeTraverser;
+$traverserB->addVisitor($visitorB);
+$stmts = $traverserA->traverser($stmts);
+$stmts = $traverserB->traverser($stmts);
+```
+
+When using multiple visitors, it is important to understand how they interact with the various
+special enterNode/leaveNode return values:
+
+ * If *any* visitor returns `DONT_TRAVERSE_CHILDREN`, the children will be skipped for *all*
+   visitors.
+ * If *any* visitor returns `DONT_TRAVERSE_CURRENT_AND_CHILDREN`, the children will be skipped for *all*
+   visitors, and all *subsequent* visitors will not visit the current node.
+ * If *any* visitor returns `STOP_TRAVERSAL`, traversal is stopped for *all* visitors.
+ * If a visitor returns a replacement node, subsequent visitors will be passed the replacement node,
+   not the original one.
+ * If a visitor returns `REMOVE_NODE`, subsequent visitors will not see this node.
+ * If a visitor returns `REPLACE_WITH_NULL`, subsequent visitors will not see this node.
+ * If a visitor returns an array of replacement nodes, subsequent visitors will see neither the node
+   that was replaced, nor the replacement nodes.
+
+Simple node finding
+-------------------
+
+While the node visitor mechanism is very flexible, creating a node visitor can be overly cumbersome
+for minor tasks. For this reason a `NodeFinder` is provided, which can find AST nodes that either
+satisfy a certain callback, or which are instances of a certain node type. A couple of examples are
+shown in the following:
+
+```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;
+});
+```
+
+Internally, the `NodeFinder` also uses a node traverser. It only simplifies the interface for a
+common use case.
+
+Parent and sibling references
+-----------------------------
+
+The node visitor mechanism is somewhat rigid, in that it prescribes an order in which nodes should
+be accessed: From parents to children. However, it can often be convenient to operate in the
+reverse direction: When working on a node, you might want to check if the parent node satisfies a
+certain property.
+
+PHP-Parser does not add parent (or sibling) references to nodes by default, but you can enable them
+using the `ParentConnectingVisitor` or `NodeConnectingVisitor`. See the [FAQ](FAQ.markdown) for
+more information.

grammar/README.md

@@ -1,28 +1,27 @@
 What do all those files mean?
 =============================
 
- * `zend_language_parser.phpy`: PHP grammer written in a pseudo language
- * `analyze.php`:               Analyzes the `.phpy`-grammer and outputs some info about it
- * `rebuildParser.php`:         Preprocesses the `.phpy`-grammar and builds the parser using `kmyacc`
- * `kmyacc.php.parser`:         A `kmyacc` parser prototype file for PHP
+ * `php.y`:              PHP 5-8 grammar written in a pseudo language
+ * `parser.template`:    A `kmyacc` parser prototype file for PHP
+ * `rebuildParsers.php`: Preprocesses the grammar and builds the parser using `kmyacc`
 
 .phpy pseudo language
 =====================
 
-The `.phpy` file is a normal grammer in `kmyacc` (`yacc`) style, with some transformations
+The `.y` file is a normal grammar in `kmyacc` (`yacc`) style, with some transformations
 applied to it:
 
  * Nodes are created using the syntax `Name[..., ...]`. This is transformed into
    `new Name(..., ..., attributes())`
- * Some function-like constructs are resolved (see `rebuildParser.php` for a list)
- * Associative arrays are written as `[key: value, ...]`, which is transformed to
-   `array('key' => value, ...)`
+ * Some function-like constructs are resolved (see `rebuildParsers.php` for a list)
 
 Building the parser
 ===================
 
-In order to rebuild the parser, you need [moriyoshi's fork of kmyacc](https://github.com/moriyoshi/kmyacc-forked).
-After you compiled/installed it, run the `rebuildParser.php` script.
+Run `php grammar/rebuildParsers.php` to rebuild the parsers. Additional options:
 
-By default only the `Parser.php` is built. If you want to additionally emit debug symbols and create `y.output`, run the
-script with `--debug`. If you want to retain the preprocessed grammar pass `--keep-tmp-grammar`.
+ * The `KMYACC` environment variable can be used to specify an alternative `kmyacc` binary.
+   By default the `phpyacc` dev dependency will be used. To use the original `kmyacc`, you
+   need to compile [moriyoshi's fork](https://github.com/moriyoshi/kmyacc-forked).
+ * The `--debug` option enables emission of debug symbols and creates the `y.output` file.
+ * The `--keep-tmp-grammar` option preserves the preprocessed grammar file.

grammar/analyze.php

@@ -1,96 +0,0 @@
-<?php
-
-const GRAMMAR_FILE = './zend_language_parser.phpy';
-
-const LIB = '(?(DEFINE)
-    (?<singleQuotedString>\'[^\\\\\']*+(?:\\\\.[^\\\\\']*+)*+\')
-    (?<doubleQuotedString>"[^\\\\"]*+(?:\\\\.[^\\\\"]*+)*+")
-    (?<string>(?&singleQuotedString)|(?&doubleQuotedString))
-    (?<comment>/\*[^*]*+(?:\*(?!/)[^*]*+)*+\*/)
-    (?<code>\{[^\'"/{}]*+(?:(?:(?&string)|(?&comment)|(?&code)|/)[^\'"/{}]*+)*+})
-)';
-
-const RULE_BLOCK = '(?<name>[a-z_]++):(?<rules>[^\'"/{};]*+(?:(?:(?&string)|(?&comment)|(?&code)|/|})[^\'"/{};]*+)*+);';
-
-$usedTerminals = array_flip(array(
-    'T_VARIABLE', 'T_STRING', 'T_INLINE_HTML', 'T_ENCAPSED_AND_WHITESPACE',
-    'T_LNUMBER', 'T_DNUMBER', 'T_CONSTANT_ENCAPSED_STRING', 'T_STRING_VARNAME', 'T_NUM_STRING'
-));
-$unusedNonterminals = array_flip(array(
-    'case_separator', 'optional_comma'
-));
-
-function regex($regex) {
-    return '~' . LIB . '(?:' . str_replace('~', '\~', $regex) . ')~';
-}
-
-function magicSplit($regex, $string) {
-    $pieces = preg_split(regex('(?:(?&string)|(?&comment)|(?&code))(*SKIP)(*FAIL)|' . $regex), $string);
-
-    foreach ($pieces as &$piece) {
-        $piece = trim($piece);
-    }
-
-    return array_filter($pieces);
-}
-
-echo '<pre>';
-
-////////////////////
-////////////////////
-////////////////////
-
-list($defs, $ruleBlocks) = magicSplit('%%', file_get_contents(GRAMMAR_FILE));
-
-if ('' !== trim(preg_replace(regex(RULE_BLOCK), '', $ruleBlocks))) {
-    die('Not all rule blocks were properly recognized!');
-}
-
-preg_match_all(regex(RULE_BLOCK), $ruleBlocks, $ruleBlocksMatches, PREG_SET_ORDER);
-foreach ($ruleBlocksMatches as $match) {
-    $ruleBlockName = $match['name'];
-    $rules = magicSplit('\|', $match['rules']);
-
-    foreach ($rules as &$rule) {
-        $parts = magicSplit('\s+', $rule);
-        $usedParts = array();
-
-        foreach ($parts as $part) {
-            if ('{' === $part[0]) {
-                preg_match_all('~\$([0-9]+)~', $part, $backReferencesMatches, PREG_SET_ORDER);
-                foreach ($backReferencesMatches as $match) {
-                    $usedParts[$match[1]] = true;
-                }
-            }
-        }
-
-        $i = 1;
-        foreach ($parts as &$part) {
-            if ('/' === $part[0]) {
-                continue;
-            }
-
-            if (isset($usedParts[$i])) {
-                if ('\'' === $part[0] || '{' === $part[0]
-                    || (ctype_upper($part[0]) && !isset($usedTerminals[$part]))
-                    || (ctype_lower($part[0]) && isset($unusedNonterminals[$part]))
-                ) {
-                    $part = '<span style="background-color: red; color: white;">' . $part . '</span>';
-                } else {
-                    $part = '<strong><em>' . $part . '</em></strong>';
-                }
-            } elseif ((ctype_upper($part[0]) && isset($usedTerminals[$part]))
-                      || (ctype_lower($part[0]) && !isset($unusedNonterminals[$part]))
-
-            ) {
-                $part = '<span style="background-color: blue; color: white;">' . $part . '</span>';
-            }
-
-            ++$i;
-        }
-
-        $rule = implode(' ', $parts);
-    }
-
-    echo $ruleBlockName, ':', "\n", '      ', implode("\n" . '    | ', $rules), "\n", ';', "\n\n";
-}

grammar/kmyacc.php.parser

@@ -1,100 +0,0 @@
-<?php
-$meta #
-#semval($) $this->semValue
-#semval($,%t) $this->semValue
-#semval(%n) $this->stackPos-(%l-%n)
-#semval(%n,%t) $this->stackPos-(%l-%n)
-
-namespace PhpParser;
-#include;
-
-/* This is an automatically GENERATED file, which should not be manually edited.
- * Instead edit one of the following:
- *  * the grammar file grammar/zend_language_parser.phpy
- *  * the skeleton file grammar/kymacc.php.parser
- *  * the preprocessing script grammar/rebuildParser.php
- */
-class Parser extends ParserAbstract
-{
-    protected $tokenToSymbolMapSize = #(YYMAXLEX);
-    protected $actionTableSize = #(YYLAST);
-    protected $gotoTableSize = #(YYGLAST);
-
-    protected $invalidSymbol = #(YYBADCH);
-    protected $errorSymbol = #(YYINTERRTOK);
-    protected $defaultAction = #(YYDEFAULT);
-    protected $unexpectedTokenRule = #(YYUNEXPECTED);
-
-    protected $YY2TBLSTATE  = #(YY2TBLSTATE);
-    protected $YYNLSTATES   = #(YYNLSTATES);
-
-#tokenval
-    const %s = %n;
-#endtokenval
-
-    protected $symbolToName = array(
-        #listvar terminals
-    );
-
-    protected $tokenToSymbol = array(
-        #listvar yytranslate
-    );
-
-    protected $action = array(
-        #listvar yyaction
-    );
-
-    protected $actionCheck = array(
-        #listvar yycheck
-    );
-
-    protected $actionBase = array(
-        #listvar yybase
-    );
-
-    protected $actionDefault = array(
-        #listvar yydefault
-    );
-
-    protected $goto = array(
-        #listvar yygoto
-    );
-
-    protected $gotoCheck = array(
-        #listvar yygcheck
-    );
-
-    protected $gotoBase = array(
-        #listvar yygbase
-    );
-
-    protected $gotoDefault = array(
-        #listvar yygdefault
-    );
-
-    protected $ruleToNonTerminal = array(
-        #listvar yylhs
-    );
-
-    protected $ruleToLength = array(
-        #listvar yylen
-    );
-#if -t
-
-    protected $productions = array(
-        #production-strings;
-    );
-#endif
-#reduce
-
-    protected function reduceRule%n() {
-        %b
-    }
-#noact
-
-    protected function reduceRule%n() {
-        $this->semValue = $this->semStack[$this->stackPos];
-    }
-#endreduce
-}
-#tailcode;

grammar/parser.template

@@ -0,0 +1,109 @@
+<?php declare(strict_types=1);
+$meta #
+#semval($) $this->semValue
+#semval($,%t) $this->semValue
+#semval(%n) $stackPos-(%l-%n)
+#semval(%n,%t) $stackPos-(%l-%n)
+
+namespace PhpParser\Parser;
+
+use PhpParser\Error;
+use PhpParser\Modifiers;
+use PhpParser\Node;
+use PhpParser\Node\Expr;
+use PhpParser\Node\Name;
+use PhpParser\Node\Scalar;
+use PhpParser\Node\Stmt;
+#include;
+
+/* This is an automatically GENERATED file, which should not be manually edited.
+ * Instead edit one of the following:
+ *  * the grammar file grammar/php.y
+ *  * the skeleton file grammar/parser.template
+ *  * the preprocessing script grammar/rebuildParsers.php
+ */
+class #(-p) extends \PhpParser\ParserAbstract
+{
+#tokenval
+    public const %s = %n;
+#endtokenval
+
+    protected int $tokenToSymbolMapSize = #(YYMAXLEX);
+    protected int $actionTableSize = #(YYLAST);
+    protected int $gotoTableSize = #(YYGLAST);
+
+    protected int $invalidSymbol = #(YYBADCH);
+    protected int $errorSymbol = #(YYINTERRTOK);
+    protected int $defaultAction = #(YYDEFAULT);
+    protected int $unexpectedTokenRule = #(YYUNEXPECTED);
+
+    protected int $YY2TBLSTATE = #(YY2TBLSTATE);
+    protected int $numNonLeafStates = #(YYNLSTATES);
+
+    protected array $symbolToName = array(
+        #listvar terminals
+    );
+
+    protected array $tokenToSymbol = array(
+        #listvar yytranslate
+    );
+
+    protected array $action = array(
+        #listvar yyaction
+    );
+
+    protected array $actionCheck = array(
+        #listvar yycheck
+    );
+
+    protected array $actionBase = array(
+        #listvar yybase
+    );
+
+    protected array $actionDefault = array(
+        #listvar yydefault
+    );
+
+    protected array $goto = array(
+        #listvar yygoto
+    );
+
+    protected array $gotoCheck = array(
+        #listvar yygcheck
+    );
+
+    protected array $gotoBase = array(
+        #listvar yygbase
+    );
+
+    protected array $gotoDefault = array(
+        #listvar yygdefault
+    );
+
+    protected array $ruleToNonTerminal = array(
+        #listvar yylhs
+    );
+
+    protected array $ruleToLength = array(
+        #listvar yylen
+    );
+#if -t
+
+    protected array $productions = array(
+        #production-strings;
+    );
+#endif
+
+    protected function initReduceCallbacks(): void {
+        $this->reduceCallbacks = [
+#reduce
+            %n => function ($stackPos) {
+                %b
+            },
+#noact
+            %n => null,
+#endreduce
+        ];
+    }
+}
+#tailcode;

grammar/phpyLang.php

@@ -0,0 +1,170 @@
+<?php declare(strict_types=1);
+
+///////////////////////////////
+/// Utility regex constants ///
+///////////////////////////////
+
+const LIB = '(?(DEFINE)
+    (?<singleQuotedString>\'[^\\\\\']*+(?:\\\\.[^\\\\\']*+)*+\')
+    (?<doubleQuotedString>"[^\\\\"]*+(?:\\\\.[^\\\\"]*+)*+")
+    (?<string>(?&singleQuotedString)|(?&doubleQuotedString))
+    (?<comment>/\*[^*]*+(?:\*(?!/)[^*]*+)*+\*/)
+    (?<code>\{[^\'"/{}]*+(?:(?:(?&string)|(?&comment)|(?&code)|/)[^\'"/{}]*+)*+})
+)';
+
+const PARAMS = '\[(?<params>[^[\]]*+(?:\[(?&params)\][^[\]]*+)*+)\]';
+const ARGS   = '\((?<args>[^()]*+(?:\((?&args)\)[^()]*+)*+)\)';
+
+///////////////////////////////
+/// Preprocessing functions ///
+///////////////////////////////
+
+function preprocessGrammar($code) {
+    $code = resolveNodes($code);
+    $code = resolveMacros($code);
+    $code = resolveStackAccess($code);
+
+    return $code;
+}
+
+function resolveNodes($code) {
+    return preg_replace_callback(
+        '~\b(?<name>[A-Z][a-zA-Z_\\\\]++)\s*' . PARAMS . '~',
+        function ($matches) {
+            // recurse
+            $matches['params'] = resolveNodes($matches['params']);
+
+            $params = magicSplit(
+                '(?:' . PARAMS . '|' . ARGS . ')(*SKIP)(*FAIL)|,',
+                $matches['params']
+            );
+
+            $paramCode = '';
+            foreach ($params as $param) {
+                $paramCode .= $param . ', ';
+            }
+
+            return 'new ' . $matches['name'] . '(' . $paramCode . 'attributes())';
+        },
+        $code
+    );
+}
+
+function resolveMacros($code) {
+    return preg_replace_callback(
+        '~\b(?<!::|->)(?!array\()(?<name>[a-z][A-Za-z]++)' . ARGS . '~',
+        function ($matches) {
+            // recurse
+            $matches['args'] = resolveMacros($matches['args']);
+
+            $name = $matches['name'];
+            $args = magicSplit(
+                '(?:' . PARAMS . '|' . ARGS . ')(*SKIP)(*FAIL)|,',
+                $matches['args']
+            );
+
+            if ('attributes' === $name) {
+                assertArgs(0, $args, $name);
+                return '$this->getAttributes($this->tokenStartStack[#1], $this->tokenEndStack[$stackPos])';
+            }
+
+            if ('stackAttributes' === $name) {
+                assertArgs(1, $args, $name);
+                return '$this->getAttributes($this->tokenStartStack[' . $args[0] . '], '
+                       . ' $this->tokenEndStack[' . $args[0] . '])';
+            }
+
+            if ('init' === $name) {
+                return '$$ = array(' . implode(', ', $args) . ')';
+            }
+
+            if ('push' === $name) {
+                assertArgs(2, $args, $name);
+
+                return $args[0] . '[] = ' . $args[1] . '; $$ = ' . $args[0];
+            }
+
+            if ('pushNormalizing' === $name) {
+                assertArgs(2, $args, $name);
+
+                return 'if (' . $args[1] . ' !== null) { ' . $args[0] . '[] = ' . $args[1] . '; } $$ = ' . $args[0] . ';';
+            }
+
+            if ('toBlock' == $name) {
+                assertArgs(1, $args, $name);
+
+                return 'if (' . $args[0] . ' instanceof Stmt\Block) { $$ = ' . $args[0] . '->stmts; } '
+                     . 'else if (' . $args[0] . ' === null) { $$ = []; } '
+                     . 'else { $$ = [' . $args[0] . ']; }';
+            }
+
+            if ('parseVar' === $name) {
+                assertArgs(1, $args, $name);
+
+                return 'substr(' . $args[0] . ', 1)';
+            }
+
+            if ('parseEncapsed' === $name) {
+                assertArgs(3, $args, $name);
+
+                return 'foreach (' . $args[0] . ' as $s) { if ($s instanceof Node\InterpolatedStringPart) {'
+                       . ' $s->value = Node\Scalar\String_::parseEscapeSequences($s->value, ' . $args[1] . ', ' . $args[2] . '); } }';
+            }
+
+            if ('makeNop' === $name) {
+                assertArgs(1, $args, $name);
+
+                return $args[0] . ' = $this->maybeCreateNop($this->tokenStartStack[#1], $this->tokenEndStack[$stackPos])';
+            }
+
+            if ('makeZeroLengthNop' == $name) {
+                assertArgs(1, $args, $name);
+
+                return $args[0] . ' = $this->maybeCreateZeroLengthNop($this->tokenPos);';
+            }
+
+            return $matches[0];
+        },
+        $code
+    );
+}
+
+function assertArgs($num, $args, $name) {
+    if ($num != count($args)) {
+        die('Wrong argument count for ' . $name . '().');
+    }
+}
+
+function resolveStackAccess($code) {
+    $code = preg_replace('/\$\d+/', '$this->semStack[$0]', $code);
+    $code = preg_replace('/#(\d+)/', '$$1', $code);
+    return $code;
+}
+
+function removeTrailingWhitespace($code) {
+    $lines = explode("\n", $code);
+    $lines = array_map('rtrim', $lines);
+    return implode("\n", $lines);
+}
+
+//////////////////////////////
+/// Regex helper functions ///
+//////////////////////////////
+
+function regex($regex) {
+    return '~' . LIB . '(?:' . str_replace('~', '\~', $regex) . ')~';
+}
+
+function magicSplit($regex, $string) {
+    $pieces = preg_split(regex('(?:(?&string)|(?&comment)|(?&code))(*SKIP)(*FAIL)|' . $regex), $string);
+
+    foreach ($pieces as &$piece) {
+        $piece = trim($piece);
+    }
+
+    if ($pieces === ['']) {
+        return [];
+    }
+
+    return $pieces;
+}

grammar/rebuildParser.php

@@ -1,228 +0,0 @@
-<?php
-
-$grammarFile           = __DIR__ . '/zend_language_parser.phpy';
-$skeletonFile          = __DIR__ . '/kmyacc.php.parser';
-$tmpGrammarFile        = __DIR__ . '/tmp_parser.phpy';
-$tmpResultFile         = __DIR__ . '/tmp_parser.php';
-$parserResultFile      = __DIR__ . '/../lib/PhpParser/Parser.php';
-
-// check for kmyacc.exe binary in this directory, otherwise fall back to global name
-$kmyacc = __DIR__ . '/kmyacc.exe';
-if (!file_exists($kmyacc)) {
-    $kmyacc = 'kmyacc';
-}
-
-$options = array_flip($argv);
-$optionDebug = isset($options['--debug']);
-$optionKeepTmpGrammar = isset($options['--keep-tmp-grammar']);
-
-///////////////////////////////
-/// Utility regex constants ///
-///////////////////////////////
-
-const LIB = '(?(DEFINE)
-    (?<singleQuotedString>\'[^\\\\\']*+(?:\\\\.[^\\\\\']*+)*+\')
-    (?<doubleQuotedString>"[^\\\\"]*+(?:\\\\.[^\\\\"]*+)*+")
-    (?<string>(?&singleQuotedString)|(?&doubleQuotedString))
-    (?<comment>/\*[^*]*+(?:\*(?!/)[^*]*+)*+\*/)
-    (?<code>\{[^\'"/{}]*+(?:(?:(?&string)|(?&comment)|(?&code)|/)[^\'"/{}]*+)*+})
-)';
-
-const PARAMS = '\[(?<params>[^[\]]*+(?:\[(?&params)\][^[\]]*+)*+)\]';
-const ARGS   = '\((?<args>[^()]*+(?:\((?&args)\)[^()]*+)*+)\)';
-
-///////////////////
-/// Main script ///
-///////////////////
-
-echo 'Building temporary preproprocessed grammar file.', "\n";
-
-$grammarCode = file_get_contents($grammarFile);
-
-$grammarCode = resolveNodes($grammarCode);
-$grammarCode = resolveMacros($grammarCode);
-$grammarCode = resolveArrays($grammarCode);
-$grammarCode = resolveStackAccess($grammarCode);
-
-file_put_contents($tmpGrammarFile, $grammarCode);
-
-$additionalArgs = $optionDebug ? '-t -v' : '';
-
-echo "Building parser.\n";
-$output = trim(shell_exec("$kmyacc $additionalArgs -l -m $skeletonFile $tmpGrammarFile 2>&1"));
-echo "Output: \"$output\"\n";
-
-$resultCode = file_get_contents($tmpResultFile);
-$resultCode = removeTrailingWhitespace($resultCode);
-
-ensureDirExists(dirname($parserResultFile));
-file_put_contents($parserResultFile, $resultCode);
-unlink($tmpResultFile);
-
-if (!$optionKeepTmpGrammar) {
-    unlink($tmpGrammarFile);
-}
-
-///////////////////////////////
-/// Preprocessing functions ///
-///////////////////////////////
-
-function resolveNodes($code) {
-    return preg_replace_callback(
-        '~(?<name>[A-Z][a-zA-Z_\\\\]++)\s*' . PARAMS . '~',
-        function($matches) {
-            // recurse
-            $matches['params'] = resolveNodes($matches['params']);
-
-            $params = magicSplit(
-                '(?:' . PARAMS . '|' . ARGS . ')(*SKIP)(*FAIL)|,',
-                $matches['params']
-            );
-
-            $paramCode = '';
-            foreach ($params as $param) {
-                $paramCode .= $param . ', ';
-            }
-
-            return 'new ' . $matches['name'] . '(' . $paramCode . 'attributes())';
-        },
-        $code
-    );
-}
-
-function resolveMacros($code) {
-    return preg_replace_callback(
-        '~\b(?<!::|->)(?!array\()(?<name>[a-z][A-Za-z]++)' . ARGS . '~',
-        function($matches) {
-            // recurse
-            $matches['args'] = resolveMacros($matches['args']);
-
-            $name = $matches['name'];
-            $args = magicSplit(
-                '(?:' . PARAMS . '|' . ARGS . ')(*SKIP)(*FAIL)|,',
-                $matches['args']
-            );
-
-            if ('attributes' == $name) {
-                assertArgs(0, $args, $name);
-                return '$this->startAttributeStack[#1] + $this->endAttributes';
-            }
-
-            if ('init' == $name) {
-                return '$$ = array(' . implode(', ', $args) . ')';
-            }
-
-            if ('push' == $name) {
-                assertArgs(2, $args, $name);
-
-                return $args[0] . '[] = ' . $args[1] . '; $$ = ' . $args[0];
-            }
-
-            if ('pushNormalizing' == $name) {
-                assertArgs(2, $args, $name);
-
-                return 'if (is_array(' . $args[1] . ')) { $$ = array_merge(' . $args[0] . ', ' . $args[1] . '); } else { ' . $args[0] . '[] = ' . $args[1] . '; $$ = ' . $args[0] . '; }';
-            }
-
-            if ('toArray' == $name) {
-                assertArgs(1, $args, $name);
-
-                return 'is_array(' . $args[0] . ') ? ' . $args[0] . ' : array(' . $args[0] . ')';
-            }
-
-            if ('parseVar' == $name) {
-                assertArgs(1, $args, $name);
-
-                return 'substr(' . $args[0] . ', 1)';
-            }
-
-            if ('parseEncapsed' == $name) {
-                assertArgs(2, $args, $name);
-
-                return 'foreach (' . $args[0] . ' as &$s) { if (is_string($s)) { $s = Node\Scalar\String_::parseEscapeSequences($s, ' . $args[1] . '); } }';
-            }
-
-            if ('parseEncapsedDoc' == $name) {
-                assertArgs(1, $args, $name);
-
-                return 'foreach (' . $args[0] . ' as &$s) { if (is_string($s)) { $s = Node\Scalar\String_::parseEscapeSequences($s, null); } } $s = preg_replace(\'~(\r\n|\n|\r)\z~\', \'\', $s); if (\'\' === $s) array_pop(' . $args[0] . ');';
-            }
-
-            return $matches[0];
-        },
-        $code
-    );
-}
-
-function assertArgs($num, $args, $name) {
-    if ($num != count($args)) {
-        die('Wrong argument count for ' . $name . '().');
-    }
-}
-
-function resolveArrays($code) {
-    return preg_replace_callback(
-        '~' . PARAMS . '~',
-        function ($matches) {
-            $elements = magicSplit(
-                '(?:' . PARAMS . '|' . ARGS . ')(*SKIP)(*FAIL)|,',
-                $matches['params']
-            );
-
-            // don't convert [] to array, it might have different meaning
-            if (empty($elements)) {
-                return $matches[0];
-            }
-
-            $elementCodes = array();
-            foreach ($elements as $element) {
-                // convert only arrays where all elements have keys
-                if (false === strpos($element, ':')) {
-                    return $matches[0];
-                }
-
-                list($key, $value) = explode(':', $element, 2);
-                $elementCodes[] = "'" . $key . "' =>" . $value;
-            }
-
-            return 'array(' . implode(', ', $elementCodes) . ')';
-        },
-        $code
-    );
-}
-
-function resolveStackAccess($code) {
-    $code = preg_replace('/\$\d+/', '$this->semStack[$0]', $code);
-    $code = preg_replace('/#(\d+)/', '$$1', $code);
-    return $code;
-}
-
-function removeTrailingWhitespace($code) {
-    $lines = explode("\n", $code);
-    $lines = array_map('rtrim', $lines);
-    return implode("\n", $lines);
-}
-
-function ensureDirExists($dir) {
-    if (!is_dir($dir)) {
-        mkdir($dir, 0777, true);
-    }
-}
-
-//////////////////////////////
-/// Regex helper functions ///
-//////////////////////////////
-
-function regex($regex) {
-    return '~' . LIB . '(?:' . str_replace('~', '\~', $regex) . ')~';
-}
-
-function magicSplit($regex, $string) {
-    $pieces = preg_split(regex('(?:(?&string)|(?&comment)|(?&code))(*SKIP)(*FAIL)|' . $regex), $string);
-
-    foreach ($pieces as &$piece) {
-        $piece = trim($piece);
-    }
-
-    return array_filter($pieces);
-}

grammar/rebuildParsers.php

@@ -0,0 +1,80 @@
+<?php declare(strict_types=1);
+
+require __DIR__ . '/phpyLang.php';
+
+$parserToDefines = [
+    'Php7' => ['PHP7' => true],
+    'Php8' => ['PHP8' => true],
+];
+
+$grammarFile    = __DIR__ . '/php.y';
+$skeletonFile   = __DIR__ . '/parser.template';
+$tmpGrammarFile = __DIR__ . '/tmp_parser.phpy';
+$tmpResultFile  = __DIR__ . '/tmp_parser.php';
+$resultDir = __DIR__ . '/../lib/PhpParser/Parser';
+
+$kmyacc = getenv('KMYACC');
+if (!$kmyacc) {
+    // Use phpyacc from dev dependencies by default.
+    $kmyacc = __DIR__ . '/../vendor/bin/phpyacc';
+}
+
+$options = array_flip($argv);
+$optionDebug = isset($options['--debug']);
+$optionKeepTmpGrammar = isset($options['--keep-tmp-grammar']);
+
+///////////////////
+/// Main script ///
+///////////////////
+
+foreach ($parserToDefines as $name => $defines) {
+    echo "Building temporary $name grammar file.\n";
+
+    $grammarCode = file_get_contents($grammarFile);
+    $grammarCode = replaceIfBlocks($grammarCode, $defines);
+    $grammarCode = preprocessGrammar($grammarCode);
+
+    file_put_contents($tmpGrammarFile, $grammarCode);
+
+    $additionalArgs = $optionDebug ? '-t -v' : '';
+
+    echo "Building $name parser.\n";
+    $output = execCmd("$kmyacc $additionalArgs -m $skeletonFile -p $name $tmpGrammarFile");
+
+    $resultCode = file_get_contents($tmpResultFile);
+    $resultCode = removeTrailingWhitespace($resultCode);
+
+    ensureDirExists($resultDir);
+    file_put_contents("$resultDir/$name.php", $resultCode);
+    unlink($tmpResultFile);
+
+    if (!$optionKeepTmpGrammar) {
+        unlink($tmpGrammarFile);
+    }
+}
+
+////////////////////////////////
+/// Utility helper functions ///
+////////////////////////////////
+
+function ensureDirExists($dir) {
+    if (!is_dir($dir)) {
+        mkdir($dir, 0777, true);
+    }
+}
+
+function execCmd($cmd) {
+    $output = trim(shell_exec("$cmd 2>&1") ?? '');
+    if ($output !== "") {
+        echo "> " . $cmd . "\n";
+        echo $output;
+    }
+    return $output;
+}
+
+function replaceIfBlocks(string $code, array $defines): string {
+    return preg_replace_callback('/\n#if\s+(\w+)\n(.*?)\n#endif/s', function ($matches) use ($defines) {
+        $value = $defines[$matches[1]] ?? false;
+        return $value ? $matches[2] : '';
+    }, $code);
+}

grammar/zend_language_parser.phpy

@@ -1,994 +0,0 @@
-%pure_parser
-%expect 2
-
-%left T_INCLUDE T_INCLUDE_ONCE T_EVAL T_REQUIRE T_REQUIRE_ONCE
-%left ','
-%left T_LOGICAL_OR
-%left T_LOGICAL_XOR
-%left T_LOGICAL_AND
-%right T_PRINT
-%right T_YIELD
-%right T_YIELD_FROM
-%left '=' T_PLUS_EQUAL T_MINUS_EQUAL T_MUL_EQUAL T_DIV_EQUAL T_CONCAT_EQUAL T_MOD_EQUAL T_AND_EQUAL T_OR_EQUAL T_XOR_EQUAL T_SL_EQUAL T_SR_EQUAL T_POW_EQUAL
-%left '?' ':'
-%right T_COALESCE
-%left T_BOOLEAN_OR
-%left T_BOOLEAN_AND
-%left '|'
-%left '^'
-%left '&'
-%nonassoc T_IS_EQUAL T_IS_NOT_EQUAL T_IS_IDENTICAL T_IS_NOT_IDENTICAL T_SPACESHIP
-%nonassoc '<' T_IS_SMALLER_OR_EQUAL '>' T_IS_GREATER_OR_EQUAL
-%left T_SL T_SR
-%left '+' '-' '.'
-%left '*' '/' '%'
-%right '!'
-%nonassoc T_INSTANCEOF
-%right '~' T_INC T_DEC T_INT_CAST T_DOUBLE_CAST T_STRING_CAST T_ARRAY_CAST T_OBJECT_CAST T_BOOL_CAST T_UNSET_CAST '@'
-%right T_POW
-%right '['
-%nonassoc T_NEW T_CLONE
-%token T_EXIT
-%token T_IF
-%left T_ELSEIF
-%left T_ELSE
-%left T_ENDIF
-%token T_LNUMBER
-%token T_DNUMBER
-%token T_STRING
-%token T_STRING_VARNAME
-%token T_VARIABLE
-%token T_NUM_STRING
-%token T_INLINE_HTML
-%token T_CHARACTER
-%token T_BAD_CHARACTER
-%token T_ENCAPSED_AND_WHITESPACE
-%token T_CONSTANT_ENCAPSED_STRING
-%token T_ECHO
-%token T_DO
-%token T_WHILE
-%token T_ENDWHILE
-%token T_FOR
-%token T_ENDFOR
-%token T_FOREACH
-%token T_ENDFOREACH
-%token T_DECLARE
-%token T_ENDDECLARE
-%token T_AS
-%token T_SWITCH
-%token T_ENDSWITCH
-%token T_CASE
-%token T_DEFAULT
-%token T_BREAK
-%token T_CONTINUE
-%token T_GOTO
-%token T_FUNCTION
-%token T_CONST
-%token T_RETURN
-%token T_TRY
-%token T_CATCH
-%token T_FINALLY
-%token T_THROW
-%token T_USE
-%token T_INSTEADOF
-%token T_GLOBAL
-%right T_STATIC T_ABSTRACT T_FINAL T_PRIVATE T_PROTECTED T_PUBLIC
-%token T_VAR
-%token T_UNSET
-%token T_ISSET
-%token T_EMPTY
-%token T_HALT_COMPILER
-%token T_CLASS
-%token T_TRAIT
-%token T_INTERFACE
-%token T_EXTENDS
-%token T_IMPLEMENTS
-%token T_OBJECT_OPERATOR
-%token T_DOUBLE_ARROW
-%token T_LIST
-%token T_ARRAY
-%token T_CALLABLE
-%token T_CLASS_C
-%token T_TRAIT_C
-%token T_METHOD_C
-%token T_FUNC_C
-%token T_LINE
-%token T_FILE
-%token T_COMMENT
-%token T_DOC_COMMENT
-%token T_OPEN_TAG
-%token T_OPEN_TAG_WITH_ECHO
-%token T_CLOSE_TAG
-%token T_WHITESPACE
-%token T_START_HEREDOC
-%token T_END_HEREDOC
-%token T_DOLLAR_OPEN_CURLY_BRACES
-%token T_CURLY_OPEN
-%token T_PAAMAYIM_NEKUDOTAYIM
-%token T_NAMESPACE
-%token T_NS_C
-%token T_DIR
-%token T_NS_SEPARATOR
-%token T_ELLIPSIS
-
-%{
-use PhpParser\Node\Expr;
-use PhpParser\Node\Name;
-use PhpParser\Node\Scalar;
-use PhpParser\Node\Stmt;
-%}
-
-%%
-
-start:
-    top_statement_list                                      { $$ = $this->handleNamespaces($1); }
-;
-
-top_statement_list:
-      top_statement_list top_statement                      { pushNormalizing($1, $2); }
-    | /* empty */                                           { init(); }
-;
-
-namespace_name_parts:
-      T_STRING                                              { init($1); }
-    | namespace_name_parts T_NS_SEPARATOR T_STRING          { push($1, $3); }
-;
-
-namespace_name:
-      namespace_name_parts                                  { $$ = Name[$1]; }
-;
-
-top_statement:
-      statement                                             { $$ = $1; }
-    | function_declaration_statement                        { $$ = $1; }
-    | class_declaration_statement                           { $$ = $1; }
-    | T_HALT_COMPILER
-          { $$ = Stmt\HaltCompiler[$this->lexer->handleHaltCompiler()]; }
-    | T_NAMESPACE namespace_name ';'                        { $$ = Stmt\Namespace_[$2, null]; }
-    | T_NAMESPACE namespace_name '{' top_statement_list '}' { $$ = Stmt\Namespace_[$2, $4]; }
-    | T_NAMESPACE '{' top_statement_list '}'                { $$ = Stmt\Namespace_[null,     $3]; }
-    | T_USE use_declarations ';'                            { $$ = Stmt\Use_[$2, Stmt\Use_::TYPE_NORMAL]; }
-    | T_USE T_FUNCTION use_declarations ';'                 { $$ = Stmt\Use_[$3, Stmt\Use_::TYPE_FUNCTION]; }
-    | T_USE T_CONST use_declarations ';'                    { $$ = Stmt\Use_[$3, Stmt\Use_::TYPE_CONSTANT]; }
-    | T_CONST constant_declaration_list ';'                 { $$ = Stmt\Const_[$2]; }
-;
-
-use_declarations:
-      use_declarations ',' use_declaration                  { push($1, $3); }
-    | use_declaration                                       { init($1); }
-;
-
-use_declaration:
-      namespace_name                                        { $$ = Stmt\UseUse[$1, null]; }
-    | namespace_name T_AS T_STRING                          { $$ = Stmt\UseUse[$1, $3]; }
-    | T_NS_SEPARATOR namespace_name                         { $$ = Stmt\UseUse[$2, null]; }
-    | T_NS_SEPARATOR namespace_name T_AS T_STRING           { $$ = Stmt\UseUse[$2, $4]; }
-;
-
-constant_declaration_list:
-      constant_declaration_list ',' constant_declaration    { push($1, $3); }
-    | constant_declaration                                  { init($1); }
-;
-
-constant_declaration:
-    T_STRING '=' static_scalar                              { $$ = Node\Const_[$1, $3]; }
-;
-
-inner_statement_list:
-      inner_statement_list inner_statement                  { pushNormalizing($1, $2); }
-    | /* empty */                                           { init(); }
-;
-
-inner_statement:
-      statement                                             { $$ = $1; }
-    | function_declaration_statement                        { $$ = $1; }
-    | class_declaration_statement                           { $$ = $1; }
-    | T_HALT_COMPILER
-          { throw new Error('__HALT_COMPILER() can only be used from the outermost scope', attributes()); }
-;
-
-statement:
-      '{' inner_statement_list '}'                          { $$ = $2; }
-    | T_IF parentheses_expr statement elseif_list else_single
-          { $$ = Stmt\If_[$2, [stmts: toArray($3), elseifs: $4, else: $5]]; }
-    | T_IF parentheses_expr ':' inner_statement_list new_elseif_list new_else_single T_ENDIF ';'
-          { $$ = Stmt\If_[$2, [stmts: $4, elseifs: $5, else: $6]]; }
-    | T_WHILE parentheses_expr while_statement              { $$ = Stmt\While_[$2, $3]; }
-    | T_DO statement T_WHILE parentheses_expr ';'           { $$ = Stmt\Do_   [$4, toArray($2)]; }
-    | T_FOR '(' for_expr ';'  for_expr ';' for_expr ')' for_statement
-          { $$ = Stmt\For_[[init: $3, cond: $5, loop: $7, stmts: $9]]; }
-    | T_SWITCH parentheses_expr switch_case_list            { $$ = Stmt\Switch_[$2, $3]; }
-    | T_BREAK ';'                                           { $$ = Stmt\Break_[null]; }
-    | T_BREAK expr ';'                                      { $$ = Stmt\Break_[$2]; }
-    | T_CONTINUE ';'                                        { $$ = Stmt\Continue_[null]; }
-    | T_CONTINUE expr ';'                                   { $$ = Stmt\Continue_[$2]; }
-    | T_RETURN ';'                                          { $$ = Stmt\Return_[null]; }
-    | T_RETURN expr ';'                                     { $$ = Stmt\Return_[$2]; }
-    | yield_expr ';'                                        { $$ = $1; }
-    | T_GLOBAL global_var_list ';'                          { $$ = Stmt\Global_[$2]; }
-    | T_STATIC static_var_list ';'                          { $$ = Stmt\Static_[$2]; }
-    | T_ECHO expr_list ';'                                  { $$ = Stmt\Echo_[$2]; }
-    | T_INLINE_HTML                                         { $$ = Stmt\InlineHTML[$1]; }
-    | expr ';'                                              { $$ = $1; }
-    | T_UNSET '(' variables_list ')' ';'                    { $$ = Stmt\Unset_[$3]; }
-    | T_FOREACH '(' expr T_AS foreach_variable ')' foreach_statement
-          { $$ = Stmt\Foreach_[$3, $5[0], [keyVar: null, byRef: $5[1], stmts: $7]]; }
-    | T_FOREACH '(' expr T_AS variable T_DOUBLE_ARROW foreach_variable ')' foreach_statement
-          { $$ = Stmt\Foreach_[$3, $7[0], [keyVar: $5, byRef: $7[1], stmts: $9]]; }
-    | T_DECLARE '(' declare_list ')' declare_statement      { $$ = Stmt\Declare_[$3, $5]; }
-    | ';'                                                   { $$ = array(); /* means: no statement */ }
-    | T_TRY '{' inner_statement_list '}' catches optional_finally
-          { $$ = Stmt\TryCatch[$3, $5, $6]; }
-    | T_THROW expr ';'                                      { $$ = Stmt\Throw_[$2]; }
-    | T_GOTO T_STRING ';'                                   { $$ = Stmt\Goto_[$2]; }
-    | T_STRING ':'                                          { $$ = Stmt\Label[$1]; }
-    | error                                                 { $$ = array(); /* means: no statement */ }
-;
-
-catches:
-      /* empty */                                           { init(); }
-    | catches catch                                         { push($1, $2); }
-;
-
-catch:
-    T_CATCH '(' name T_VARIABLE ')' '{' inner_statement_list '}'
-        { $$ = Stmt\Catch_[$3, parseVar($4), $7]; }
-;
-
-optional_finally:
-      /* empty */                                           { $$ = null; }
-    | T_FINALLY '{' inner_statement_list '}'                { $$ = $3; }
-;
-
-variables_list:
-      variable                                              { init($1); }
-    | variables_list ',' variable                           { push($1, $3); }
-;
-
-optional_ref:
-      /* empty */                                           { $$ = false; }
-    | '&'                                                   { $$ = true; }
-;
-
-optional_ellipsis:
-      /* empty */                                           { $$ = false; }
-    | T_ELLIPSIS                                            { $$ = true; }
-;
-
-function_declaration_statement:
-    T_FUNCTION optional_ref T_STRING '(' parameter_list ')' optional_return_type '{' inner_statement_list '}'
-        { $$ = Stmt\Function_[$3, [byRef: $2, params: $5, returnType: $7, stmts: $9]]; }
-;
-
-class_declaration_statement:
-      class_entry_type T_STRING extends_from implements_list '{' class_statement_list '}'
-          { $$ = Stmt\Class_[$2, [type: $1, extends: $3, implements: $4, stmts: $6]]; }
-    | T_INTERFACE T_STRING interface_extends_list '{' class_statement_list '}'
-          { $$ = Stmt\Interface_[$2, [extends: $3, stmts: $5]]; }
-    | T_TRAIT T_STRING '{' class_statement_list '}'
-          { $$ = Stmt\Trait_[$2, $4]; }
-;
-
-class_entry_type:
-      T_CLASS                                               { $$ = 0; }
-    | T_ABSTRACT T_CLASS                                    { $$ = Stmt\Class_::MODIFIER_ABSTRACT; }
-    | T_FINAL T_CLASS                                       { $$ = Stmt\Class_::MODIFIER_FINAL; }
-;
-
-extends_from:
-      /* empty */                                           { $$ = null; }
-    | T_EXTENDS name                                        { $$ = $2; }
-;
-
-interface_extends_list:
-      /* empty */                                           { $$ = array(); }
-    | T_EXTENDS name_list                                   { $$ = $2; }
-;
-
-implements_list:
-      /* empty */                                           { $$ = array(); }
-    | T_IMPLEMENTS name_list                                { $$ = $2; }
-;
-
-name_list:
-      name                                                  { init($1); }
-    | name_list ',' name                                    { push($1, $3); }
-;
-
-for_statement:
-      statement                                             { $$ = toArray($1); }
-    | ':' inner_statement_list T_ENDFOR ';'                 { $$ = $2; }
-;
-
-foreach_statement:
-      statement                                             { $$ = toArray($1); }
-    | ':' inner_statement_list T_ENDFOREACH ';'             { $$ = $2; }
-;
-
-declare_statement:
-      statement                                             { $$ = toArray($1); }
-    | ':' inner_statement_list T_ENDDECLARE ';'             { $$ = $2; }
-;
-
-declare_list:
-      declare_list_element                                  { init($1); }
-    | declare_list ',' declare_list_element                 { push($1, $3); }
-;
-
-declare_list_element:
-      T_STRING '=' static_scalar                            { $$ = Stmt\DeclareDeclare[$1, $3]; }
-;
-
-switch_case_list:
-      '{' case_list '}'                                     { $$ = $2; }
-    | '{' ';' case_list '}'                                 { $$ = $3; }
-    | ':' case_list T_ENDSWITCH ';'                         { $$ = $2; }
-    | ':' ';' case_list T_ENDSWITCH ';'                     { $$ = $3; }
-;
-
-case_list:
-      /* empty */                                           { init(); }
-    | case_list case                                        { push($1, $2); }
-;
-
-case:
-      T_CASE expr case_separator inner_statement_list       { $$ = Stmt\Case_[$2, $4]; }
-    | T_DEFAULT case_separator inner_statement_list         { $$ = Stmt\Case_[null, $3]; }
-;
-
-case_separator:
-      ':'
-    | ';'
-;
-
-while_statement:
-      statement                                             { $$ = toArray($1); }
-    | ':' inner_statement_list T_ENDWHILE ';'               { $$ = $2; }
-;
-
-elseif_list:
-      /* empty */                                           { init(); }
-    | elseif_list elseif                                    { push($1, $2); }
-;
-
-elseif:
-      T_ELSEIF parentheses_expr statement                   { $$ = Stmt\ElseIf_[$2, toArray($3)]; }
-;
-
-new_elseif_list:
-      /* empty */                                           { init(); }
-    | new_elseif_list new_elseif                            { push($1, $2); }
-;
-
-new_elseif:
-     T_ELSEIF parentheses_expr ':' inner_statement_list     { $$ = Stmt\ElseIf_[$2, $4]; }
-;
-
-else_single:
-      /* empty */                                           { $$ = null; }
-    | T_ELSE statement                                      { $$ = Stmt\Else_[toArray($2)]; }
-;
-
-new_else_single:
-      /* empty */                                           { $$ = null; }
-    | T_ELSE ':' inner_statement_list                       { $$ = Stmt\Else_[$3]; }
-;
-
-foreach_variable:
-      variable                                              { $$ = array($1, false); }
-    | '&' variable                                          { $$ = array($2, true); }
-    | list_expr                                             { $$ = array($1, false); }
-;
-
-parameter_list:
-      non_empty_parameter_list                              { $$ = $1; }
-    | /* empty */                                           { $$ = array(); }
-;
-
-non_empty_parameter_list:
-      parameter                                             { init($1); }
-    | non_empty_parameter_list ',' parameter                { push($1, $3); }
-;
-
-parameter:
-      optional_param_type optional_ref optional_ellipsis T_VARIABLE
-          { $$ = Node\Param[parseVar($4), null, $1, $2, $3]; }
-    | optional_param_type optional_ref optional_ellipsis T_VARIABLE '=' static_scalar
-          { $$ = Node\Param[parseVar($4), $6, $1, $2, $3]; }
-;
-
-type:
-      name                                                  { $$ = $1; }
-    | T_ARRAY                                               { $$ = 'array'; }
-    | T_CALLABLE                                            { $$ = 'callable'; }
-;
-
-optional_param_type:
-      /* empty */                                           { $$ = null; }
-    | type                                                  { $$ = $1; }
-;
-
-optional_return_type:
-      /* empty */                                           { $$ = null; }
-    | ':' type                                              { $$ = $2; }
-;
-
-argument_list:
-      '(' ')'                                               { $$ = array(); }
-    | '(' non_empty_argument_list ')'                       { $$ = $2; }
-    | '(' yield_expr ')'                                    { $$ = array(Node\Arg[$2, false, false]); }
-;
-
-non_empty_argument_list:
-      argument                                              { init($1); }
-    | non_empty_argument_list ',' argument                  { push($1, $3); }
-;
-
-argument:
-      expr                                                  { $$ = Node\Arg[$1, false, false]; }
-    | '&' variable                                          { $$ = Node\Arg[$2, true, false]; }
-    | T_ELLIPSIS expr                                       { $$ = Node\Arg[$2, false, true]; }
-;
-
-global_var_list:
-      global_var_list ',' global_var                        { push($1, $3); }
-    | global_var                                            { init($1); }
-;
-
-global_var:
-      T_VARIABLE                                            { $$ = Expr\Variable[parseVar($1)]; }
-    | '$' variable                                          { $$ = Expr\Variable[$2]; }
-    | '$' '{' expr '}'                                      { $$ = Expr\Variable[$3]; }
-;
-
-static_var_list:
-      static_var_list ',' static_var                        { push($1, $3); }
-    | static_var                                            { init($1); }
-;
-
-static_var:
-      T_VARIABLE                                            { $$ = Stmt\StaticVar[parseVar($1), null]; }
-    | T_VARIABLE '=' static_scalar                          { $$ = Stmt\StaticVar[parseVar($1), $3]; }
-;
-
-class_statement_list:
-      class_statement_list class_statement                  { push($1, $2); }
-    | /* empty */                                           { init(); }
-;
-
-class_statement:
-      variable_modifiers property_declaration_list ';'      { $$ = Stmt\Property[$1, $2]; }
-    | T_CONST constant_declaration_list ';'                 { $$ = Stmt\ClassConst[$2]; }
-    | method_modifiers T_FUNCTION optional_ref T_STRING '(' parameter_list ')' optional_return_type method_body
-          { $$ = Stmt\ClassMethod[$4, [type: $1, byRef: $3, params: $6, returnType: $8, stmts: $9]]; }
-    | T_USE name_list trait_adaptations                     { $$ = Stmt\TraitUse[$2, $3]; }
-;
-
-trait_adaptations:
-      ';'                                                   { $$ = array(); }
-    | '{' trait_adaptation_list '}'                         { $$ = $2; }
-;
-
-trait_adaptation_list:
-      /* empty */                                           { init(); }
-    | trait_adaptation_list trait_adaptation                { push($1, $2); }
-;
-
-trait_adaptation:
-      trait_method_reference_fully_qualified T_INSTEADOF name_list ';'
-          { $$ = Stmt\TraitUseAdaptation\Precedence[$1[0], $1[1], $3]; }
-    | trait_method_reference T_AS member_modifier T_STRING ';'
-          { $$ = Stmt\TraitUseAdaptation\Alias[$1[0], $1[1], $3, $4]; }
-    | trait_method_reference T_AS member_modifier ';'
-          { $$ = Stmt\TraitUseAdaptation\Alias[$1[0], $1[1], $3, null]; }
-    | trait_method_reference T_AS T_STRING ';'
-          { $$ = Stmt\TraitUseAdaptation\Alias[$1[0], $1[1], null, $3]; }
-;
-
-trait_method_reference_fully_qualified:
-      name T_PAAMAYIM_NEKUDOTAYIM T_STRING                  { $$ = array($1, $3); }
-;
-trait_method_reference:
-      trait_method_reference_fully_qualified                { $$ = $1; }
-    | T_STRING                                              { $$ = array(null, $1); }
-;
-
-method_body:
-      ';' /* abstract method */                             { $$ = null; }
-    | '{' inner_statement_list '}'                          { $$ = $2; }
-;
-
-variable_modifiers:
-      non_empty_member_modifiers                            { $$ = $1; }
-    | T_VAR                                                 { $$ = 0; }
-;
-
-method_modifiers:
-      /* empty */                                           { $$ = 0; }
-    | non_empty_member_modifiers                            { $$ = $1; }
-;
-
-non_empty_member_modifiers:
-      member_modifier                                       { $$ = $1; }
-    | non_empty_member_modifiers member_modifier            { Stmt\Class_::verifyModifier($1, $2); $$ = $1 | $2; }
-;
-
-member_modifier:
-      T_PUBLIC                                              { $$ = Stmt\Class_::MODIFIER_PUBLIC; }
-    | T_PROTECTED                                           { $$ = Stmt\Class_::MODIFIER_PROTECTED; }
-    | T_PRIVATE                                             { $$ = Stmt\Class_::MODIFIER_PRIVATE; }
-    | T_STATIC                                              { $$ = Stmt\Class_::MODIFIER_STATIC; }
-    | T_ABSTRACT                                            { $$ = Stmt\Class_::MODIFIER_ABSTRACT; }
-    | T_FINAL                                               { $$ = Stmt\Class_::MODIFIER_FINAL; }
-;
-
-property_declaration_list:
-      property_declaration                                  { init($1); }
-    | property_declaration_list ',' property_declaration    { push($1, $3); }
-;
-
-property_declaration:
-      T_VARIABLE                                            { $$ = Stmt\PropertyProperty[parseVar($1), null]; }
-    | T_VARIABLE '=' static_scalar                          { $$ = Stmt\PropertyProperty[parseVar($1), $3]; }
-;
-
-expr_list:
-      expr_list ',' expr                                    { push($1, $3); }
-    | expr                                                  { init($1); }
-;
-
-for_expr:
-      /* empty */                                           { $$ = array(); }
-    | expr_list                                             { $$ = $1; }
-;
-
-expr:
-      variable                                              { $$ = $1; }
-    | list_expr '=' expr                                    { $$ = Expr\Assign[$1, $3]; }
-    | variable '=' expr                                     { $$ = Expr\Assign[$1, $3]; }
-    | variable '=' '&' variable                             { $$ = Expr\AssignRef[$1, $4]; }
-    | variable '=' '&' new_expr                             { $$ = Expr\AssignRef[$1, $4]; }
-    | new_expr                                              { $$ = $1; }
-    | T_CLONE expr                                          { $$ = Expr\Clone_[$2]; }
-    | variable T_PLUS_EQUAL expr                            { $$ = Expr\AssignOp\Plus      [$1, $3]; }
-    | variable T_MINUS_EQUAL expr                           { $$ = Expr\AssignOp\Minus     [$1, $3]; }
-    | variable T_MUL_EQUAL expr                             { $$ = Expr\AssignOp\Mul       [$1, $3]; }
-    | variable T_DIV_EQUAL expr                             { $$ = Expr\AssignOp\Div       [$1, $3]; }
-    | variable T_CONCAT_EQUAL expr                          { $$ = Expr\AssignOp\Concat    [$1, $3]; }
-    | variable T_MOD_EQUAL expr                             { $$ = Expr\AssignOp\Mod       [$1, $3]; }
-    | variable T_AND_EQUAL expr                             { $$ = Expr\AssignOp\BitwiseAnd[$1, $3]; }
-    | variable T_OR_EQUAL expr                              { $$ = Expr\AssignOp\BitwiseOr [$1, $3]; }
-    | variable T_XOR_EQUAL expr                             { $$ = Expr\AssignOp\BitwiseXor[$1, $3]; }
-    | variable T_SL_EQUAL expr                              { $$ = Expr\AssignOp\ShiftLeft [$1, $3]; }
-    | variable T_SR_EQUAL expr                              { $$ = Expr\AssignOp\ShiftRight[$1, $3]; }
-    | variable T_POW_EQUAL expr                             { $$ = Expr\AssignOp\Pow       [$1, $3]; }
-    | variable T_INC                                        { $$ = Expr\PostInc[$1]; }
-    | T_INC variable                                        { $$ = Expr\PreInc [$2]; }
-    | variable T_DEC                                        { $$ = Expr\PostDec[$1]; }
-    | T_DEC variable                                        { $$ = Expr\PreDec [$2]; }
-    | expr T_BOOLEAN_OR expr                                { $$ = Expr\BinaryOp\BooleanOr [$1, $3]; }
-    | expr T_BOOLEAN_AND expr                               { $$ = Expr\BinaryOp\BooleanAnd[$1, $3]; }
-    | expr T_LOGICAL_OR expr                                { $$ = Expr\BinaryOp\LogicalOr [$1, $3]; }
-    | expr T_LOGICAL_AND expr                               { $$ = Expr\BinaryOp\LogicalAnd[$1, $3]; }
-    | expr T_LOGICAL_XOR expr                               { $$ = Expr\BinaryOp\LogicalXor[$1, $3]; }
-    | expr '|' expr                                         { $$ = Expr\BinaryOp\BitwiseOr [$1, $3]; }
-    | expr '&' expr                                         { $$ = Expr\BinaryOp\BitwiseAnd[$1, $3]; }
-    | expr '^' expr                                         { $$ = Expr\BinaryOp\BitwiseXor[$1, $3]; }
-    | expr '.' expr                                         { $$ = Expr\BinaryOp\Concat    [$1, $3]; }
-    | expr '+' expr                                         { $$ = Expr\BinaryOp\Plus      [$1, $3]; }
-    | expr '-' expr                                         { $$ = Expr\BinaryOp\Minus     [$1, $3]; }
-    | expr '*' expr                                         { $$ = Expr\BinaryOp\Mul       [$1, $3]; }
-    | expr '/' expr                                         { $$ = Expr\BinaryOp\Div       [$1, $3]; }
-    | expr '%' expr                                         { $$ = Expr\BinaryOp\Mod       [$1, $3]; }
-    | expr T_SL expr                                        { $$ = Expr\BinaryOp\ShiftLeft [$1, $3]; }
-    | expr T_SR expr                                        { $$ = Expr\BinaryOp\ShiftRight[$1, $3]; }
-    | expr T_POW expr                                       { $$ = Expr\BinaryOp\Pow       [$1, $3]; }
-    | '+' expr %prec T_INC                                  { $$ = Expr\UnaryPlus [$2]; }
-    | '-' expr %prec T_INC                                  { $$ = Expr\UnaryMinus[$2]; }
-    | '!' expr                                              { $$ = Expr\BooleanNot[$2]; }
-    | '~' expr                                              { $$ = Expr\BitwiseNot[$2]; }
-    | expr T_IS_IDENTICAL expr                              { $$ = Expr\BinaryOp\Identical     [$1, $3]; }
-    | expr T_IS_NOT_IDENTICAL expr                          { $$ = Expr\BinaryOp\NotIdentical  [$1, $3]; }
-    | expr T_IS_EQUAL expr                                  { $$ = Expr\BinaryOp\Equal         [$1, $3]; }
-    | expr T_IS_NOT_EQUAL expr                              { $$ = Expr\BinaryOp\NotEqual      [$1, $3]; }
-    | expr T_SPACESHIP expr                                 { $$ = Expr\BinaryOp\Spaceship     [$1, $3]; }
-    | expr '<' expr                                         { $$ = Expr\BinaryOp\Smaller       [$1, $3]; }
-    | expr T_IS_SMALLER_OR_EQUAL expr                       { $$ = Expr\BinaryOp\SmallerOrEqual[$1, $3]; }
-    | expr '>' expr                                         { $$ = Expr\BinaryOp\Greater       [$1, $3]; }
-    | expr T_IS_GREATER_OR_EQUAL expr                       { $$ = Expr\BinaryOp\GreaterOrEqual[$1, $3]; }
-    | expr T_INSTANCEOF class_name_reference                { $$ = Expr\Instanceof_[$1, $3]; }
-    | parentheses_expr                                      { $$ = $1; }
-    /* we need a separate '(' new_expr ')' rule to avoid problems caused by a s/r conflict */
-    | '(' new_expr ')'                                      { $$ = $2; }
-    | expr '?' expr ':' expr                                { $$ = Expr\Ternary[$1, $3,   $5]; }
-    | expr '?' ':' expr                                     { $$ = Expr\Ternary[$1, null, $4]; }
-    | expr T_COALESCE expr                                  { $$ = Expr\BinaryOp\Coalesce[$1, $3]; }
-    | T_ISSET '(' variables_list ')'                        { $$ = Expr\Isset_[$3]; }
-    | T_EMPTY '(' expr ')'                                  { $$ = Expr\Empty_[$3]; }
-    | T_INCLUDE expr                                        { $$ = Expr\Include_[$2, Expr\Include_::TYPE_INCLUDE]; }
-    | T_INCLUDE_ONCE expr                                   { $$ = Expr\Include_[$2, Expr\Include_::TYPE_INCLUDE_ONCE]; }
-    | T_EVAL parentheses_expr                               { $$ = Expr\Eval_[$2]; }
-    | T_REQUIRE expr                                        { $$ = Expr\Include_[$2, Expr\Include_::TYPE_REQUIRE]; }
-    | T_REQUIRE_ONCE expr                                   { $$ = Expr\Include_[$2, Expr\Include_::TYPE_REQUIRE_ONCE]; }
-    | T_INT_CAST expr                                       { $$ = Expr\Cast\Int_    [$2]; }
-    | T_DOUBLE_CAST expr                                    { $$ = Expr\Cast\Double  [$2]; }
-    | T_STRING_CAST expr                                    { $$ = Expr\Cast\String_ [$2]; }
-    | T_ARRAY_CAST expr                                     { $$ = Expr\Cast\Array_  [$2]; }
-    | T_OBJECT_CAST expr                                    { $$ = Expr\Cast\Object_ [$2]; }
-    | T_BOOL_CAST expr                                      { $$ = Expr\Cast\Bool_   [$2]; }
-    | T_UNSET_CAST expr                                     { $$ = Expr\Cast\Unset_  [$2]; }
-    | T_EXIT exit_expr                                      { $$ = Expr\Exit_        [$2]; }
-    | '@' expr                                              { $$ = Expr\ErrorSuppress[$2]; }
-    | scalar                                                { $$ = $1; }
-    | array_expr                                            { $$ = $1; }
-    | scalar_dereference                                    { $$ = $1; }
-    | '`' backticks_expr '`'                                { $$ = Expr\ShellExec[$2]; }
-    | T_PRINT expr                                          { $$ = Expr\Print_[$2]; }
-    | T_YIELD                                               { $$ = Expr\Yield_[null, null]; }
-    | T_YIELD_FROM expr                                     { $$ = Expr\YieldFrom[$2]; }
-    | T_FUNCTION optional_ref '(' parameter_list ')' lexical_vars optional_return_type
-      '{' inner_statement_list '}'
-          { $$ = Expr\Closure[[static: false, byRef: $2, params: $4, uses: $6, returnType: $7, stmts: $9]]; }
-    | T_STATIC T_FUNCTION optional_ref '(' parameter_list ')' lexical_vars optional_return_type
-      '{' inner_statement_list '}'
-          { $$ = Expr\Closure[[static: true, byRef: $3, params: $5, uses: $7, returnType: $8, stmts: $10]]; }
-;
-
-parentheses_expr:
-      '(' expr ')'                                          { $$ = $2; }
-    | '(' yield_expr ')'                                    { $$ = $2; }
-;
-
-yield_expr:
-      T_YIELD expr                                          { $$ = Expr\Yield_[$2, null]; }
-    | T_YIELD expr T_DOUBLE_ARROW expr                      { $$ = Expr\Yield_[$4, $2]; }
-;
-
-array_expr:
-      T_ARRAY '(' array_pair_list ')'                       { $$ = Expr\Array_[$3]; }
-    | '[' array_pair_list ']'                               { $$ = Expr\Array_[$2]; }
-;
-
-scalar_dereference:
-      array_expr '[' dim_offset ']'                         { $$ = Expr\ArrayDimFetch[$1, $3]; }
-    | T_CONSTANT_ENCAPSED_STRING '[' dim_offset ']'
-          { $$ = Expr\ArrayDimFetch[Scalar\String_[Scalar\String_::parse($1)], $3]; }
-    | constant '[' dim_offset ']'                           { $$ = Expr\ArrayDimFetch[$1, $3]; }
-    | scalar_dereference '[' dim_offset ']'                 { $$ = Expr\ArrayDimFetch[$1, $3]; }
-    /* alternative array syntax missing intentionally */
-;
-
-anonymous_class:
-      T_CLASS ctor_arguments extends_from implements_list '{' class_statement_list '}'
-          { $$ = array(Stmt\Class_[null, [type: 0, extends: $3, implements: $4, stmts: $6]], $2); }
-
-new_expr:
-      T_NEW class_name_reference ctor_arguments             { $$ = Expr\New_[$2, $3]; }
-    | T_NEW anonymous_class
-          { list($class, $ctorArgs) = $2; $$ = Expr\New_[$class, $ctorArgs]; }
-;
-
-lexical_vars:
-      /* empty */                                           { $$ = array(); }
-    | T_USE '(' lexical_var_list ')'                        { $$ = $3; }
-;
-
-lexical_var_list:
-      lexical_var                                           { init($1); }
-    | lexical_var_list ',' lexical_var                      { push($1, $3); }
-;
-
-lexical_var:
-      optional_ref T_VARIABLE                               { $$ = Expr\ClosureUse[parseVar($2), $1]; }
-;
-
-function_call:
-      name argument_list                                    { $$ = Expr\FuncCall[$1, $2]; }
-    | class_name_or_var T_PAAMAYIM_NEKUDOTAYIM T_STRING argument_list
-          { $$ = Expr\StaticCall[$1, $3, $4]; }
-    | class_name_or_var T_PAAMAYIM_NEKUDOTAYIM '{' expr '}' argument_list
-          { $$ = Expr\StaticCall[$1, $4, $6]; }
-    | static_property argument_list {
-            if ($1 instanceof Node\Expr\StaticPropertyFetch) {
-                $$ = Expr\StaticCall[$1->class, Expr\Variable[$1->name], $2];
-            } elseif ($1 instanceof Node\Expr\ArrayDimFetch) {
-                $tmp = $1;
-                while ($tmp->var instanceof Node\Expr\ArrayDimFetch) {
-                    $tmp = $tmp->var;
-                }
-
-                $$ = Expr\StaticCall[$tmp->var->class, $1, $2];
-                $tmp->var = Expr\Variable[$tmp->var->name];
-            } else {
-                throw new \Exception;
-            }
-          }
-    | variable_without_objects argument_list
-          { $$ = Expr\FuncCall[$1, $2]; }
-    | function_call '[' dim_offset ']'                      { $$ = Expr\ArrayDimFetch[$1, $3]; }
-      /* alternative array syntax missing intentionally */
-;
-
-class_name:
-      T_STATIC                                              { $$ = Name[$1]; }
-    | name                                                  { $$ = $1; }
-;
-
-name:
-      namespace_name_parts                                  { $$ = Name[$1]; }
-    | T_NS_SEPARATOR namespace_name_parts                   { $$ = Name\FullyQualified[$2]; }
-    | T_NAMESPACE T_NS_SEPARATOR namespace_name_parts       { $$ = Name\Relative[$3]; }
-;
-
-class_name_reference:
-      class_name                                            { $$ = $1; }
-    | dynamic_class_name_reference                          { $$ = $1; }
-;
-
-dynamic_class_name_reference:
-      object_access_for_dcnr                                { $$ = $1; }
-    | base_variable                                         { $$ = $1; }
-;
-
-class_name_or_var:
-      class_name                                            { $$ = $1; }
-    | reference_variable                                    { $$ = $1; }
-;
-
-object_access_for_dcnr:
-      base_variable T_OBJECT_OPERATOR object_property
-          { $$ = Expr\PropertyFetch[$1, $3]; }
-    | object_access_for_dcnr T_OBJECT_OPERATOR object_property
-          { $$ = Expr\PropertyFetch[$1, $3]; }
-    | object_access_for_dcnr '[' dim_offset ']'             { $$ = Expr\ArrayDimFetch[$1, $3]; }
-    | object_access_for_dcnr '{' expr '}'                   { $$ = Expr\ArrayDimFetch[$1, $3]; }
-;
-
-exit_expr:
-      /* empty */                                           { $$ = null; }
-    | '(' ')'                                               { $$ = null; }
-    | parentheses_expr                                      { $$ = $1; }
-;
-
-backticks_expr:
-      /* empty */                                           { $$ = array(); }
-    | T_ENCAPSED_AND_WHITESPACE                             { $$ = array(Scalar\String_::parseEscapeSequences($1, '`')); }
-    | encaps_list                                           { parseEncapsed($1, '`'); $$ = $1; }
-;
-
-ctor_arguments:
-      /* empty */                                           { $$ = array(); }
-    | argument_list                                         { $$ = $1; }
-;
-
-common_scalar:
-      T_LNUMBER                                             { $$ = Scalar\LNumber[Scalar\LNumber::parse($1)]; }
-    | T_DNUMBER                                             { $$ = Scalar\DNumber[Scalar\DNumber::parse($1)]; }
-    | T_CONSTANT_ENCAPSED_STRING                            { $$ = Scalar\String_[Scalar\String_::parse($1)]; }
-    | T_LINE                                                { $$ = Scalar\MagicConst\Line[]; }
-    | T_FILE                                                { $$ = Scalar\MagicConst\File[]; }
-    | T_DIR                                                 { $$ = Scalar\MagicConst\Dir[]; }
-    | T_CLASS_C                                             { $$ = Scalar\MagicConst\Class_[]; }
-    | T_TRAIT_C                                             { $$ = Scalar\MagicConst\Trait_[]; }
-    | T_METHOD_C                                            { $$ = Scalar\MagicConst\Method[]; }
-    | T_FUNC_C                                              { $$ = Scalar\MagicConst\Function_[]; }
-    | T_NS_C                                                { $$ = Scalar\MagicConst\Namespace_[]; }
-    | T_START_HEREDOC T_ENCAPSED_AND_WHITESPACE T_END_HEREDOC
-          { $$ = Scalar\String_[Scalar\String_::parseDocString($1, $2)]; }
-    | T_START_HEREDOC T_END_HEREDOC
-          { $$ = Scalar\String_['']; }
-;
-
-static_scalar:
-      common_scalar                                         { $$ = $1; }
-    | class_name T_PAAMAYIM_NEKUDOTAYIM class_const_name    { $$ = Expr\ClassConstFetch[$1, $3]; }
-    | name                                                  { $$ = Expr\ConstFetch[$1]; }
-    | T_ARRAY '(' static_array_pair_list ')'                { $$ = Expr\Array_[$3]; }
-    | '[' static_array_pair_list ']'                        { $$ = Expr\Array_[$2]; }
-    | static_operation                                      { $$ = $1; }
-;
-
-static_operation:
-      static_scalar T_BOOLEAN_OR static_scalar              { $$ = Expr\BinaryOp\BooleanOr [$1, $3]; }
-    | static_scalar T_BOOLEAN_AND static_scalar             { $$ = Expr\BinaryOp\BooleanAnd[$1, $3]; }
-    | static_scalar T_LOGICAL_OR static_scalar              { $$ = Expr\BinaryOp\LogicalOr [$1, $3]; }
-    | static_scalar T_LOGICAL_AND static_scalar             { $$ = Expr\BinaryOp\LogicalAnd[$1, $3]; }
-    | static_scalar T_LOGICAL_XOR static_scalar             { $$ = Expr\BinaryOp\LogicalXor[$1, $3]; }
-    | static_scalar '|' static_scalar                       { $$ = Expr\BinaryOp\BitwiseOr [$1, $3]; }
-    | static_scalar '&' static_scalar                       { $$ = Expr\BinaryOp\BitwiseAnd[$1, $3]; }
-    | static_scalar '^' static_scalar                       { $$ = Expr\BinaryOp\BitwiseXor[$1, $3]; }
-    | static_scalar '.' static_scalar                       { $$ = Expr\BinaryOp\Concat    [$1, $3]; }
-    | static_scalar '+' static_scalar                       { $$ = Expr\BinaryOp\Plus      [$1, $3]; }
-    | static_scalar '-' static_scalar                       { $$ = Expr\BinaryOp\Minus     [$1, $3]; }
-    | static_scalar '*' static_scalar                       { $$ = Expr\BinaryOp\Mul       [$1, $3]; }
-    | static_scalar '/' static_scalar                       { $$ = Expr\BinaryOp\Div       [$1, $3]; }
-    | static_scalar '%' static_scalar                       { $$ = Expr\BinaryOp\Mod       [$1, $3]; }
-    | static_scalar T_SL static_scalar                      { $$ = Expr\BinaryOp\ShiftLeft [$1, $3]; }
-    | static_scalar T_SR static_scalar                      { $$ = Expr\BinaryOp\ShiftRight[$1, $3]; }
-    | static_scalar T_POW static_scalar                     { $$ = Expr\BinaryOp\Pow       [$1, $3]; }
-    | '+' static_scalar %prec T_INC                         { $$ = Expr\UnaryPlus [$2]; }
-    | '-' static_scalar %prec T_INC                         { $$ = Expr\UnaryMinus[$2]; }
-    | '!' static_scalar                                     { $$ = Expr\BooleanNot[$2]; }
-    | '~' static_scalar                                     { $$ = Expr\BitwiseNot[$2]; }
-    | static_scalar T_IS_IDENTICAL static_scalar            { $$ = Expr\BinaryOp\Identical     [$1, $3]; }
-    | static_scalar T_IS_NOT_IDENTICAL static_scalar        { $$ = Expr\BinaryOp\NotIdentical  [$1, $3]; }
-    | static_scalar T_IS_EQUAL static_scalar                { $$ = Expr\BinaryOp\Equal         [$1, $3]; }
-    | static_scalar T_IS_NOT_EQUAL static_scalar            { $$ = Expr\BinaryOp\NotEqual      [$1, $3]; }
-    | static_scalar '<' static_scalar                       { $$ = Expr\BinaryOp\Smaller       [$1, $3]; }
-    | static_scalar T_IS_SMALLER_OR_EQUAL static_scalar     { $$ = Expr\BinaryOp\SmallerOrEqual[$1, $3]; }
-    | static_scalar '>' static_scalar                       { $$ = Expr\BinaryOp\Greater       [$1, $3]; }
-    | static_scalar T_IS_GREATER_OR_EQUAL static_scalar     { $$ = Expr\BinaryOp\GreaterOrEqual[$1, $3]; }
-    | static_scalar '?' static_scalar ':' static_scalar     { $$ = Expr\Ternary[$1, $3,   $5]; }
-    | static_scalar '?' ':' static_scalar                   { $$ = Expr\Ternary[$1, null, $4]; }
-    | static_scalar '[' static_scalar ']'                   { $$ = Expr\ArrayDimFetch[$1, $3]; }
-    | '(' static_scalar ')'                                 { $$ = $2; }
-;
-
-constant:
-      name                                                  { $$ = Expr\ConstFetch[$1]; }
-    | class_name_or_var T_PAAMAYIM_NEKUDOTAYIM class_const_name
-          { $$ = Expr\ClassConstFetch[$1, $3]; }
-;
-
-scalar:
-      common_scalar                                         { $$ = $1; }
-    | constant                                              { $$ = $1; }
-    | '"' encaps_list '"'
-          { parseEncapsed($2, '"'); $$ = Scalar\Encapsed[$2]; }
-    | T_START_HEREDOC encaps_list T_END_HEREDOC
-          { parseEncapsedDoc($2); $$ = Scalar\Encapsed[$2]; }
-;
-
-class_const_name:
-      T_STRING                                              { $$ = $1; }
-    | T_CLASS                                               { $$ = 'class'; }
-;
-
-static_array_pair_list:
-      /* empty */                                           { $$ = array(); }
-    | non_empty_static_array_pair_list optional_comma       { $$ = $1; }
-;
-
-optional_comma:
-      /* empty */
-    | ','
-;
-
-non_empty_static_array_pair_list:
-      non_empty_static_array_pair_list ',' static_array_pair { push($1, $3); }
-    | static_array_pair                                      { init($1); }
-;
-
-static_array_pair:
-      static_scalar T_DOUBLE_ARROW static_scalar            { $$ = Expr\ArrayItem[$3, $1,   false]; }
-    | static_scalar                                         { $$ = Expr\ArrayItem[$1, null, false]; }
-;
-
-variable:
-      object_access                                         { $$ = $1; }
-    | base_variable                                         { $$ = $1; }
-    | function_call                                         { $$ = $1; }
-    | new_expr_array_deref                                  { $$ = $1; }
-;
-
-new_expr_array_deref:
-      '(' new_expr ')' '[' dim_offset ']'                   { $$ = Expr\ArrayDimFetch[$2, $5]; }
-    | new_expr_array_deref '[' dim_offset ']'               { $$ = Expr\ArrayDimFetch[$1, $3]; }
-      /* alternative array syntax missing intentionally */
-;
-
-object_access:
-      variable_or_new_expr T_OBJECT_OPERATOR object_property
-          { $$ = Expr\PropertyFetch[$1, $3]; }
-    | variable_or_new_expr T_OBJECT_OPERATOR object_property argument_list
-          { $$ = Expr\MethodCall[$1, $3, $4]; }
-    | object_access argument_list                           { $$ = Expr\FuncCall[$1, $2]; }
-    | object_access '[' dim_offset ']'                      { $$ = Expr\ArrayDimFetch[$1, $3]; }
-    | object_access '{' expr '}'                            { $$ = Expr\ArrayDimFetch[$1, $3]; }
-;
-
-variable_or_new_expr:
-      variable                                              { $$ = $1; }
-    | '(' new_expr ')'                                      { $$ = $2; }
-;
-
-variable_without_objects:
-      reference_variable                                    { $$ = $1; }
-    | '$' variable_without_objects                          { $$ = Expr\Variable[$2]; }
-;
-
-base_variable:
-      variable_without_objects                              { $$ = $1; }
-    | static_property                                       { $$ = $1; }
-;
-
-static_property:
-      class_name_or_var T_PAAMAYIM_NEKUDOTAYIM '$' reference_variable
-          { $$ = Expr\StaticPropertyFetch[$1, $4]; }
-    | static_property_with_arrays                           { $$ = $1; }
-;
-
-static_property_with_arrays:
-      class_name_or_var T_PAAMAYIM_NEKUDOTAYIM T_VARIABLE
-          { $$ = Expr\StaticPropertyFetch[$1, parseVar($3)]; }
-    | class_name_or_var T_PAAMAYIM_NEKUDOTAYIM '$' '{' expr '}'
-          { $$ = Expr\StaticPropertyFetch[$1, $5]; }
-    | static_property_with_arrays '[' dim_offset ']'        { $$ = Expr\ArrayDimFetch[$1, $3]; }
-    | static_property_with_arrays '{' expr '}'              { $$ = Expr\ArrayDimFetch[$1, $3]; }
-;
-
-reference_variable:
-      reference_variable '[' dim_offset ']'                 { $$ = Expr\ArrayDimFetch[$1, $3]; }
-    | reference_variable '{' expr '}'                       { $$ = Expr\ArrayDimFetch[$1, $3]; }
-    | T_VARIABLE                                            { $$ = Expr\Variable[parseVar($1)]; }
-    | '$' '{' expr '}'                                      { $$ = Expr\Variable[$3]; }
-;
-
-dim_offset:
-      /* empty */                                           { $$ = null; }
-    | expr                                                  { $$ = $1; }
-;
-
-object_property:
-      T_STRING                                              { $$ = $1; }
-    | '{' expr '}'                                          { $$ = $2; }
-    | variable_without_objects                              { $$ = $1; }
-;
-
-list_expr:
-      T_LIST '(' list_expr_elements ')'                     { $$ = Expr\List_[$3]; }
-;
-
-list_expr_elements:
-      list_expr_elements ',' list_expr_element              { push($1, $3); }
-    | list_expr_element                                     { init($1); }
-;
-
-list_expr_element:
-      variable                                              { $$ = $1; }
-    | list_expr                                             { $$ = $1; }
-    | /* empty */                                           { $$ = null; }
-;
-
-array_pair_list:
-      /* empty */                                           { $$ = array(); }
-    | non_empty_array_pair_list optional_comma              { $$ = $1; }
-;
-
-non_empty_array_pair_list:
-      non_empty_array_pair_list ',' array_pair              { push($1, $3); }
-    | array_pair                                            { init($1); }
-;
-
-array_pair:
-      expr T_DOUBLE_ARROW expr                              { $$ = Expr\ArrayItem[$3, $1,   false]; }
-    | expr                                                  { $$ = Expr\ArrayItem[$1, null, false]; }
-    | expr T_DOUBLE_ARROW '&' variable                      { $$ = Expr\ArrayItem[$4, $1,   true]; }
-    | '&' variable                                          { $$ = Expr\ArrayItem[$2, null, true]; }
-;
-
-encaps_list:
-      encaps_list encaps_var                                { push($1, $2); }
-    | encaps_list T_ENCAPSED_AND_WHITESPACE                 { push($1, $2); }
-    | encaps_var                                            { init($1); }
-    | T_ENCAPSED_AND_WHITESPACE encaps_var                  { init($1, $2); }
-;
-
-encaps_var:
-      T_VARIABLE                                            { $$ = Expr\Variable[parseVar($1)]; }
-    | T_VARIABLE '[' encaps_var_offset ']'                  { $$ = Expr\ArrayDimFetch[Expr\Variable[parseVar($1)], $3]; }
-    | T_VARIABLE T_OBJECT_OPERATOR T_STRING                 { $$ = Expr\PropertyFetch[Expr\Variable[parseVar($1)], $3]; }
-    | T_DOLLAR_OPEN_CURLY_BRACES expr '}'                   { $$ = Expr\Variable[$2]; }
-    | T_DOLLAR_OPEN_CURLY_BRACES T_STRING_VARNAME '}'       { $$ = Expr\Variable[$2]; }
-    | T_DOLLAR_OPEN_CURLY_BRACES T_STRING_VARNAME '[' expr ']' '}'
-          { $$ = Expr\ArrayDimFetch[Expr\Variable[$2], $4]; }
-    | T_CURLY_OPEN variable '}'                             { $$ = $2; }
-;
-
-encaps_var_offset:
-      T_STRING                                              { $$ = Scalar\String_[$1]; }
-    | T_NUM_STRING                                          { $$ = Scalar\String_[$1]; }
-    | T_VARIABLE                                            { $$ = Expr\Variable[parseVar($1)]; }
-;
-
-%%

lib/PhpParser/Autoloader.php

@@ -1,275 +0,0 @@
-<?php
-
-namespace PhpParser;
-
-/**
- * @codeCoverageIgnore
- */
-class Autoloader
-{
-    /** @var bool Whether the autoloader has been registered. */
-    private static $registered = false;
-
-    /** @var bool Whether we're running on PHP 7. */
-    private static $runningOnPhp7;
-
-    /**
-     * Registers PhpParser\Autoloader as an SPL autoloader.
-     *
-     * @param bool $prepend Whether to prepend the autoloader instead of appending
-     */
-    static public function register($prepend = false) {
-        if (self::$registered === true) {
-            return;
-        }
-
-        spl_autoload_register(array(__CLASS__, 'autoload'), true, $prepend);
-        self::$registered = true;
-        self::$runningOnPhp7 = version_compare(PHP_VERSION, '7.0-dev', '>=');
-    }
-
-    /**
-     * Handles autoloading of classes.
-     *
-     * @param string $class A class name.
-     */
-    static public function autoload($class) {
-        if (0 === strpos($class, 'PhpParser\\')) {
-            if (isset(self::$php7AliasesOldToNew[$class])) {
-                if (self::$runningOnPhp7) {
-                    return;
-                }
-
-                // Load the new class, alias will be registered afterwards
-                $class = self::$php7AliasesOldToNew[$class];
-            }
-
-            $fileName = dirname(__DIR__) . '/' . strtr($class, '\\', '/') . '.php';
-            if (file_exists($fileName)) {
-                require $fileName;
-            }
-
-            if (isset(self::$php7AliasesNewToOld[$class])) {
-                // New class name was used, register alias for old one, otherwise
-                // it won't be usable in "instanceof" and other non-autoloading places.
-                if (!self::$runningOnPhp7) {
-                    class_alias($class, self::$php7AliasesNewToOld[$class]);
-                }
-            }
-        } else if (0 === strpos($class, 'PHPParser_')) {
-            if (isset(self::$nonNamespacedAliases[$class])) {
-                // Register all aliases at once to avoid dependency issues
-                self::registerNonNamespacedAliases();
-            }
-        }
-    }
-
-    private static function registerNonNamespacedAliases() {
-        foreach (self::$nonNamespacedAliases as $old => $new) {
-            class_alias($new, $old);
-        }
-    }
-
-    private static $php7AliasesOldToNew = array(
-        'PhpParser\Node\Expr\Cast\Bool' => 'PhpParser\Node\Expr\Cast\Bool_',
-        'PhpParser\Node\Expr\Cast\Int' => 'PhpParser\Node\Expr\Cast\Int_',
-        'PhpParser\Node\Expr\Cast\Object' => 'PhpParser\Node\Expr\Cast\Object_',
-        'PhpParser\Node\Expr\Cast\String' => 'PhpParser\Node\Expr\Cast\String_',
-        'PhpParser\Node\Scalar\String' => 'PhpParser\Node\Scalar\String_',
-    );
-
-    private static $php7AliasesNewToOld = array(
-        'PhpParser\Node\Expr\Cast\Bool_' => 'PhpParser\Node\Expr\Cast\Bool',
-        'PhpParser\Node\Expr\Cast\Int_' => 'PhpParser\Node\Expr\Cast\Int',
-        'PhpParser\Node\Expr\Cast\Object_' => 'PhpParser\Node\Expr\Cast\Object',
-        'PhpParser\Node\Expr\Cast\String_' => 'PhpParser\Node\Expr\Cast\String',
-        'PhpParser\Node\Scalar\String_' => 'PhpParser\Node\Scalar\String',
-    );
-
-    private static $nonNamespacedAliases = array(
-        'PHPParser_Builder' => 'PhpParser\Builder',
-        'PHPParser_BuilderAbstract' => 'PhpParser\BuilderAbstract',
-        'PHPParser_BuilderFactory' => 'PhpParser\BuilderFactory',
-        'PHPParser_Comment' => 'PhpParser\Comment',
-        'PHPParser_Comment_Doc' => 'PhpParser\Comment\Doc',
-        'PHPParser_Error' => 'PhpParser\Error',
-        'PHPParser_Lexer' => 'PhpParser\Lexer',
-        'PHPParser_Lexer_Emulative' => 'PhpParser\Lexer\Emulative',
-        'PHPParser_Node' => 'PhpParser\Node',
-        'PHPParser_NodeAbstract' => 'PhpParser\NodeAbstract',
-        'PHPParser_NodeDumper' => 'PhpParser\NodeDumper',
-        'PHPParser_NodeTraverser' => 'PhpParser\NodeTraverser',
-        'PHPParser_NodeTraverserInterface' => 'PhpParser\NodeTraverserInterface',
-        'PHPParser_NodeVisitor' => 'PhpParser\NodeVisitor',
-        'PHPParser_NodeVisitor_NameResolver' => 'PhpParser\NodeVisitor\NameResolver',
-        'PHPParser_NodeVisitorAbstract' => 'PhpParser\NodeVisitorAbstract',
-        'PHPParser_Parser' => 'PhpParser\Parser',
-        'PHPParser_PrettyPrinterAbstract' => 'PhpParser\PrettyPrinterAbstract',
-        'PHPParser_PrettyPrinter_Default' => 'PhpParser\PrettyPrinter\Standard',
-        'PHPParser_PrettyPrinter_Zend' => 'PhpParser\PrettyPrinter\Standard',
-        'PHPParser_Serializer' => 'PhpParser\Serializer',
-        'PHPParser_Serializer_XML' => 'PhpParser\Serializer\XML',
-        'PHPParser_Unserializer' => 'PhpParser\Unserializer',
-        'PHPParser_Unserializer_XML' => 'PhpParser\Unserializer\XML',
-
-        'PHPParser_Builder_Class' => 'PhpParser\Builder\Class_',
-        'PHPParser_Builder_Function' => 'PhpParser\Builder\Function_',
-        'PHPParser_Builder_Interface' => 'PhpParser\Builder\Interface_',
-        'PHPParser_Builder_Method' => 'PhpParser\Builder\Method',
-        'PHPParser_Builder_Param' => 'PhpParser\Builder\Param',
-        'PHPParser_Builder_Property' => 'PhpParser\Builder\Property',
-
-        'PHPParser_Node_Arg' => 'PhpParser\Node\Arg',
-        'PHPParser_Node_Const' => 'PhpParser\Node\Const_',
-        'PHPParser_Node_Expr' => 'PhpParser\Node\Expr',
-        'PHPParser_Node_Name' => 'PhpParser\Node\Name',
-        'PHPParser_Node_Name_FullyQualified' => 'PhpParser\Node\Name\FullyQualified',
-        'PHPParser_Node_Name_Relative' => 'PhpParser\Node\Name\Relative',
-        'PHPParser_Node_Param' => 'PhpParser\Node\Param',
-        'PHPParser_Node_Scalar' => 'PhpParser\Node\Scalar',
-        'PHPParser_Node_Stmt' => 'PhpParser\Node\Stmt',
-
-        'PHPParser_Node_Stmt_Break' => 'PhpParser\Node\Stmt\Break_',
-        'PHPParser_Node_Stmt_Case' => 'PhpParser\Node\Stmt\Case_',
-        'PHPParser_Node_Stmt_Catch' => 'PhpParser\Node\Stmt\Catch_',
-        'PHPParser_Node_Stmt_Class' => 'PhpParser\Node\Stmt\Class_',
-        'PHPParser_Node_Stmt_ClassConst' => 'PhpParser\Node\Stmt\ClassConst',
-        'PHPParser_Node_Stmt_ClassMethod' => 'PhpParser\Node\Stmt\ClassMethod',
-        'PHPParser_Node_Stmt_Const' => 'PhpParser\Node\Stmt\Const_',
-        'PHPParser_Node_Stmt_Continue' => 'PhpParser\Node\Stmt\Continue_',
-        'PHPParser_Node_Stmt_Declare' => 'PhpParser\Node\Stmt\Declare_',
-        'PHPParser_Node_Stmt_DeclareDeclare' => 'PhpParser\Node\Stmt\DeclareDeclare',
-        'PHPParser_Node_Stmt_Do' => 'PhpParser\Node\Stmt\Do_',
-        'PHPParser_Node_Stmt_Echo' => 'PhpParser\Node\Stmt\Echo_',
-        'PHPParser_Node_Stmt_Else' => 'PhpParser\Node\Stmt\Else_',
-        'PHPParser_Node_Stmt_ElseIf' => 'PhpParser\Node\Stmt\ElseIf_',
-        'PHPParser_Node_Stmt_For' => 'PhpParser\Node\Stmt\For_',
-        'PHPParser_Node_Stmt_Foreach' => 'PhpParser\Node\Stmt\Foreach_',
-        'PHPParser_Node_Stmt_Function' => 'PhpParser\Node\Stmt\Function_',
-        'PHPParser_Node_Stmt_Global' => 'PhpParser\Node\Stmt\Global_',
-        'PHPParser_Node_Stmt_Goto' => 'PhpParser\Node\Stmt\Goto_',
-        'PHPParser_Node_Stmt_HaltCompiler' => 'PhpParser\Node\Stmt\HaltCompiler',
-        'PHPParser_Node_Stmt_If' => 'PhpParser\Node\Stmt\If_',
-        'PHPParser_Node_Stmt_InlineHTML' => 'PhpParser\Node\Stmt\InlineHTML',
-        'PHPParser_Node_Stmt_Interface' => 'PhpParser\Node\Stmt\Interface_',
-        'PHPParser_Node_Stmt_Label' => 'PhpParser\Node\Stmt\Label',
-        'PHPParser_Node_Stmt_Namespace' => 'PhpParser\Node\Stmt\Namespace_',
-        'PHPParser_Node_Stmt_Property' => 'PhpParser\Node\Stmt\Property',
-        'PHPParser_Node_Stmt_PropertyProperty' => 'PhpParser\Node\Stmt\PropertyProperty',
-        'PHPParser_Node_Stmt_Return' => 'PhpParser\Node\Stmt\Return_',
-        'PHPParser_Node_Stmt_Static' => 'PhpParser\Node\Stmt\Static_',
-        'PHPParser_Node_Stmt_StaticVar' => 'PhpParser\Node\Stmt\StaticVar',
-        'PHPParser_Node_Stmt_Switch' => 'PhpParser\Node\Stmt\Switch_',
-        'PHPParser_Node_Stmt_Throw' => 'PhpParser\Node\Stmt\Throw_',
-        'PHPParser_Node_Stmt_Trait' => 'PhpParser\Node\Stmt\Trait_',
-        'PHPParser_Node_Stmt_TraitUse' => 'PhpParser\Node\Stmt\TraitUse',
-        'PHPParser_Node_Stmt_TraitUseAdaptation' => 'PhpParser\Node\Stmt\TraitUseAdaptation',
-        'PHPParser_Node_Stmt_TraitUseAdaptation_Alias' => 'PhpParser\Node\Stmt\TraitUseAdaptation\Alias',
-        'PHPParser_Node_Stmt_TraitUseAdaptation_Precedence' => 'PhpParser\Node\Stmt\TraitUseAdaptation\Precedence',
-        'PHPParser_Node_Stmt_TryCatch' => 'PhpParser\Node\Stmt\TryCatch',
-        'PHPParser_Node_Stmt_Unset' => 'PhpParser\Node\Stmt\Unset_',
-        'PHPParser_Node_Stmt_UseUse' => 'PhpParser\Node\Stmt\UseUse',
-        'PHPParser_Node_Stmt_Use' => 'PhpParser\Node\Stmt\Use_',
-        'PHPParser_Node_Stmt_While' => 'PhpParser\Node\Stmt\While_',
-
-        'PHPParser_Node_Expr_AssignBitwiseAnd' => 'PhpParser\Node\Expr\AssignOp\BitwiseAnd',
-        'PHPParser_Node_Expr_AssignBitwiseOr' => 'PhpParser\Node\Expr\AssignOp\BitwiseOr',
-        'PHPParser_Node_Expr_AssignBitwiseXor' => 'PhpParser\Node\Expr\AssignOp\BitwiseXor',
-        'PHPParser_Node_Expr_AssignConcat' => 'PhpParser\Node\Expr\AssignOp\Concat',
-        'PHPParser_Node_Expr_AssignDiv' => 'PhpParser\Node\Expr\AssignOp\Div',
-        'PHPParser_Node_Expr_AssignMinus' => 'PhpParser\Node\Expr\AssignOp\Minus',
-        'PHPParser_Node_Expr_AssignMod' => 'PhpParser\Node\Expr\AssignOp\Mod',
-        'PHPParser_Node_Expr_AssignMul' => 'PhpParser\Node\Expr\AssignOp\Mul',
-        'PHPParser_Node_Expr_AssignPlus' => 'PhpParser\Node\Expr\AssignOp\Plus',
-        'PHPParser_Node_Expr_AssignShiftLeft' => 'PhpParser\Node\Expr\AssignOp\ShiftLeft',
-        'PHPParser_Node_Expr_AssignShiftRight' => 'PhpParser\Node\Expr\AssignOp\ShiftRight',
-
-        'PHPParser_Node_Expr_Cast' => 'PhpParser\Node\Expr\Cast',
-        'PHPParser_Node_Expr_Cast_Array' => 'PhpParser\Node\Expr\Cast\Array_',
-        'PHPParser_Node_Expr_Cast_Bool' => 'PhpParser\Node\Expr\Cast\Bool_',
-        'PHPParser_Node_Expr_Cast_Double' => 'PhpParser\Node\Expr\Cast\Double',
-        'PHPParser_Node_Expr_Cast_Int' => 'PhpParser\Node\Expr\Cast\Int_',
-        'PHPParser_Node_Expr_Cast_Object' => 'PhpParser\Node\Expr\Cast\Object_',
-        'PHPParser_Node_Expr_Cast_String' => 'PhpParser\Node\Expr\Cast\String_',
-        'PHPParser_Node_Expr_Cast_Unset' => 'PhpParser\Node\Expr\Cast\Unset_',
-
-        'PHPParser_Node_Expr_BitwiseAnd' => 'PhpParser\Node\Expr\BinaryOp\BitwiseAnd',
-        'PHPParser_Node_Expr_BitwiseOr' => 'PhpParser\Node\Expr\BinaryOp\BitwiseOr',
-        'PHPParser_Node_Expr_BitwiseXor' => 'PhpParser\Node\Expr\BinaryOp\BitwiseXor',
-        'PHPParser_Node_Expr_BooleanAnd' => 'PhpParser\Node\Expr\BinaryOp\BooleanAnd',
-        'PHPParser_Node_Expr_BooleanOr' => 'PhpParser\Node\Expr\BinaryOp\BooleanOr',
-        'PHPParser_Node_Expr_Concat' => 'PhpParser\Node\Expr\BinaryOp\Concat',
-        'PHPParser_Node_Expr_Div' => 'PhpParser\Node\Expr\BinaryOp\Div',
-        'PHPParser_Node_Expr_Equal' => 'PhpParser\Node\Expr\BinaryOp\Equal',
-        'PHPParser_Node_Expr_Greater' => 'PhpParser\Node\Expr\BinaryOp\Greater',
-        'PHPParser_Node_Expr_GreaterOrEqual' => 'PhpParser\Node\Expr\BinaryOp\GreaterOrEqual',
-        'PHPParser_Node_Expr_Identical' => 'PhpParser\Node\Expr\BinaryOp\Identical',
-        'PHPParser_Node_Expr_LogicalAnd' => 'PhpParser\Node\Expr\BinaryOp\LogicalAnd',
-        'PHPParser_Node_Expr_LogicalOr' => 'PhpParser\Node\Expr\BinaryOp\LogicalOr',
-        'PHPParser_Node_Expr_LogicalXor' => 'PhpParser\Node\Expr\BinaryOp\LogicalXor',
-        'PHPParser_Node_Expr_Minus' => 'PhpParser\Node\Expr\BinaryOp\Minus',
-        'PHPParser_Node_Expr_Mod' => 'PhpParser\Node\Expr\BinaryOp\Mod',
-        'PHPParser_Node_Expr_Mul' => 'PhpParser\Node\Expr\BinaryOp\Mul',
-        'PHPParser_Node_Expr_NotEqual' => 'PhpParser\Node\Expr\BinaryOp\NotEqual',
-        'PHPParser_Node_Expr_NotIdentical' => 'PhpParser\Node\Expr\BinaryOp\NotIdentical',
-        'PHPParser_Node_Expr_Plus' => 'PhpParser\Node\Expr\BinaryOp\Plus',
-        'PHPParser_Node_Expr_ShiftLeft' => 'PhpParser\Node\Expr\BinaryOp\ShiftLeft',
-        'PHPParser_Node_Expr_ShiftRight' => 'PhpParser\Node\Expr\BinaryOp\ShiftRight',
-        'PHPParser_Node_Expr_Smaller' => 'PhpParser\Node\Expr\BinaryOp\Smaller',
-        'PHPParser_Node_Expr_SmallerOrEqual' => 'PhpParser\Node\Expr\BinaryOp\SmallerOrEqual',
-
-        'PHPParser_Node_Expr_Array' => 'PhpParser\Node\Expr\Array_',
-        'PHPParser_Node_Expr_ArrayDimFetch' => 'PhpParser\Node\Expr\ArrayDimFetch',
-        'PHPParser_Node_Expr_ArrayItem' => 'PhpParser\Node\Expr\ArrayItem',
-        'PHPParser_Node_Expr_Assign' => 'PhpParser\Node\Expr\Assign',
-        'PHPParser_Node_Expr_AssignRef' => 'PhpParser\Node\Expr\AssignRef',
-        'PHPParser_Node_Expr_BitwiseNot' => 'PhpParser\Node\Expr\BitwiseNot',
-        'PHPParser_Node_Expr_BooleanNot' => 'PhpParser\Node\Expr\BooleanNot',
-        'PHPParser_Node_Expr_ClassConstFetch' => 'PhpParser\Node\Expr\ClassConstFetch',
-        'PHPParser_Node_Expr_Clone' => 'PhpParser\Node\Expr\Clone_',
-        'PHPParser_Node_Expr_Closure' => 'PhpParser\Node\Expr\Closure',
-        'PHPParser_Node_Expr_ClosureUse' => 'PhpParser\Node\Expr\ClosureUse',
-        'PHPParser_Node_Expr_ConstFetch' => 'PhpParser\Node\Expr\ConstFetch',
-        'PHPParser_Node_Expr_Empty' => 'PhpParser\Node\Expr\Empty_',
-        'PHPParser_Node_Expr_ErrorSuppress' => 'PhpParser\Node\Expr\ErrorSuppress',
-        'PHPParser_Node_Expr_Eval' => 'PhpParser\Node\Expr\Eval_',
-        'PHPParser_Node_Expr_Exit' => 'PhpParser\Node\Expr\Exit_',
-        'PHPParser_Node_Expr_FuncCall' => 'PhpParser\Node\Expr\FuncCall',
-        'PHPParser_Node_Expr_Include' => 'PhpParser\Node\Expr\Include_',
-        'PHPParser_Node_Expr_Instanceof' => 'PhpParser\Node\Expr\Instanceof_',
-        'PHPParser_Node_Expr_Isset' => 'PhpParser\Node\Expr\Isset_',
-        'PHPParser_Node_Expr_List' => 'PhpParser\Node\Expr\List_',
-        'PHPParser_Node_Expr_MethodCall' => 'PhpParser\Node\Expr\MethodCall',
-        'PHPParser_Node_Expr_New' => 'PhpParser\Node\Expr\New_',
-        'PHPParser_Node_Expr_PostDec' => 'PhpParser\Node\Expr\PostDec',
-        'PHPParser_Node_Expr_PostInc' => 'PhpParser\Node\Expr\PostInc',
-        'PHPParser_Node_Expr_PreDec' => 'PhpParser\Node\Expr\PreDec',
-        'PHPParser_Node_Expr_PreInc' => 'PhpParser\Node\Expr\PreInc',
-        'PHPParser_Node_Expr_Print' => 'PhpParser\Node\Expr\Print_',
-        'PHPParser_Node_Expr_PropertyFetch' => 'PhpParser\Node\Expr\PropertyFetch',
-        'PHPParser_Node_Expr_ShellExec' => 'PhpParser\Node\Expr\ShellExec',
-        'PHPParser_Node_Expr_StaticCall' => 'PhpParser\Node\Expr\StaticCall',
-        'PHPParser_Node_Expr_StaticPropertyFetch' => 'PhpParser\Node\Expr\StaticPropertyFetch',
-        'PHPParser_Node_Expr_Ternary' => 'PhpParser\Node\Expr\Ternary',
-        'PHPParser_Node_Expr_UnaryMinus' => 'PhpParser\Node\Expr\UnaryMinus',
-        'PHPParser_Node_Expr_UnaryPlus' => 'PhpParser\Node\Expr\UnaryPlus',
-        'PHPParser_Node_Expr_Variable' => 'PhpParser\Node\Expr\Variable',
-        'PHPParser_Node_Expr_Yield' => 'PhpParser\Node\Expr\Yield_',
-
-        'PHPParser_Node_Scalar_ClassConst' => 'PhpParser\Node\Scalar\MagicConst\Class_',
-        'PHPParser_Node_Scalar_DirConst' => 'PhpParser\Node\Scalar\MagicConst\Dir',
-        'PHPParser_Node_Scalar_FileConst' => 'PhpParser\Node\Scalar\MagicConst\File',
-        'PHPParser_Node_Scalar_FuncConst' => 'PhpParser\Node\Scalar\MagicConst\Function_',
-        'PHPParser_Node_Scalar_LineConst' => 'PhpParser\Node\Scalar\MagicConst\Line',
-        'PHPParser_Node_Scalar_MethodConst' => 'PhpParser\Node\Scalar\MagicConst\Method',
-        'PHPParser_Node_Scalar_NSConst' => 'PhpParser\Node\Scalar\MagicConst\Namespace_',
-        'PHPParser_Node_Scalar_TraitConst' => 'PhpParser\Node\Scalar\MagicConst\Trait_',
-
-        'PHPParser_Node_Scalar_DNumber' => 'PhpParser\Node\Scalar\DNumber',
-        'PHPParser_Node_Scalar_Encapsed' => 'PhpParser\Node\Scalar\Encapsed',
-        'PHPParser_Node_Scalar_LNumber' => 'PhpParser\Node\Scalar\LNumber',
-        'PHPParser_Node_Scalar_String' => 'PhpParser\Node\Scalar\String_',
-    );
-}
-
-class_alias('PhpParser\Autoloader', 'PHPParser_Autoloader');

lib/PhpParser/Builder.php

@@ -1,13 +1,12 @@
-<?php
+<?php declare(strict_types=1);
 
 namespace PhpParser;
 
-interface Builder
-{
+interface Builder {
     /**
      * Returns the built node.
      *
      * @return Node The built node
      */
-    public function getNode();
-}
+    public function getNode(): Node;
+}

lib/PhpParser/Builder/ClassConst.php

@@ -0,0 +1,150 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhpParser\Builder;
+
+use PhpParser;
+use PhpParser\BuilderHelpers;
+use PhpParser\Modifiers;
+use PhpParser\Node;
+use PhpParser\Node\Const_;
+use PhpParser\Node\Identifier;
+use PhpParser\Node\Stmt;
+
+class ClassConst implements PhpParser\Builder {
+    protected int $flags = 0;
+    /** @var array<string, mixed> */
+    protected array $attributes = [];
+    /** @var list<Const_> */
+    protected array $constants = [];
+
+    /** @var list<Node\AttributeGroup> */
+    protected array $attributeGroups = [];
+    /** @var Identifier|Node\Name|Node\ComplexType|null */
+    protected ?Node $type = null;
+
+    /**
+     * Creates a class constant builder
+     *
+     * @param string|Identifier $name Name
+     * @param Node\Expr|bool|null|int|float|string|array $value Value
+     */
+    public function __construct($name, $value) {
+        $this->constants = [new Const_($name, BuilderHelpers::normalizeValue($value))];
+    }
+
+    /**
+     * Add another constant to const group
+     *
+     * @param string|Identifier $name Name
+     * @param Node\Expr|bool|null|int|float|string|array $value Value
+     *
+     * @return $this The builder instance (for fluid interface)
+     */
+    public function addConst($name, $value) {
+        $this->constants[] = new Const_($name, BuilderHelpers::normalizeValue($value));
+
+        return $this;
+    }
+
+    /**
+     * Makes the constant public.
+     *
+     * @return $this The builder instance (for fluid interface)
+     */
+    public function makePublic() {
+        $this->flags = BuilderHelpers::addModifier($this->flags, Modifiers::PUBLIC);
+
+        return $this;
+    }
+
+    /**
+     * Makes the constant protected.
+     *
+     * @return $this The builder instance (for fluid interface)
+     */
+    public function makeProtected() {
+        $this->flags = BuilderHelpers::addModifier($this->flags, Modifiers::PROTECTED);
+
+        return $this;
+    }
+
+    /**
+     * Makes the constant private.
+     *
+     * @return $this The builder instance (for fluid interface)
+     */
+    public function makePrivate() {
+        $this->flags = BuilderHelpers::addModifier($this->flags, Modifiers::PRIVATE);
+
+        return $this;
+    }
+
+    /**
+     * Makes the constant final.
+     *
+     * @return $this The builder instance (for fluid interface)
+     */
+    public function makeFinal() {
+        $this->flags = BuilderHelpers::addModifier($this->flags, Modifiers::FINAL);
+
+        return $this;
+    }
+
+    /**
+     * Sets doc comment for the constant.
+     *
+     * @param PhpParser\Comment\Doc|string $docComment Doc comment to set
+     *
+     * @return $this The builder instance (for fluid interface)
+     */
+    public function setDocComment($docComment) {
+        $this->attributes = [
+            'comments' => [BuilderHelpers::normalizeDocComment($docComment)]
+        ];
+
+        return $this;
+    }
+
+    /**
+     * Adds an attribute group.
+     *
+     * @param Node\Attribute|Node\AttributeGroup $attribute
+     *
+     * @return $this The builder instance (for fluid interface)
+     */
+    public function addAttribute($attribute) {
+        $this->attributeGroups[] = BuilderHelpers::normalizeAttribute($attribute);
+
+        return $this;
+    }
+
+    /**
+     * Sets the constant type.
+     *
+     * @param string|Node\Name|Identifier|Node\ComplexType $type
+     *
+     * @return $this
+     */
+    public function setType($type) {
+        $this->type = BuilderHelpers::normalizeType($type);
+
+        return $this;
+    }
+
+    /**
+     * Returns the built class node.
+     *
+     * @return Stmt\ClassConst The built constant node
+     */
+    public function getNode(): PhpParser\Node {
+        return new Stmt\ClassConst(
+            $this->constants,
+            $this->flags,
+            $this->attributes,
+            $this->attributeGroups,
+            $this->type
+        );
+    }
+}

lib/PhpParser/Builder/Class_.php

@@ -1,30 +1,37 @@
-<?php
+<?php declare(strict_types=1);
 
 namespace PhpParser\Builder;
 
 use PhpParser;
+use PhpParser\BuilderHelpers;
+use PhpParser\Modifiers;
+use PhpParser\Node;
 use PhpParser\Node\Name;
 use PhpParser\Node\Stmt;
 
-class Class_ extends Declaration
-{
-    protected $name;
-
-    protected $extends = null;
-    protected $implements = array();
-    protected $type = 0;
-
-    protected $uses = array();
-    protected $constants = array();
-    protected $properties = array();
-    protected $methods = array();
+class Class_ extends Declaration {
+    protected string $name;
+    protected ?Name $extends = null;
+    /** @var list<Name> */
+    protected array $implements = [];
+    protected int $flags = 0;
+    /** @var list<Stmt\TraitUse> */
+    protected array $uses = [];
+    /** @var list<Stmt\ClassConst> */
+    protected array $constants = [];
+    /** @var list<Stmt\Property> */
+    protected array $properties = [];
+    /** @var list<Stmt\ClassMethod> */
+    protected array $methods = [];
+    /** @var list<Node\AttributeGroup> */
+    protected array $attributeGroups = [];
 
     /**
      * Creates a class builder.
      *
      * @param string $name Name of the class
      */
-    public function __construct($name) {
+    public function __construct(string $name) {
         $this->name = $name;
     }
 
@@ -36,7 +43,7 @@ class Class_ extends Declaration
      * @return $this The builder instance (for fluid interface)
      */
     public function extend($class) {
-        $this->extends = $this->normalizeName($class);
+        $this->extends = BuilderHelpers::normalizeName($class);
 
         return $this;
     }
@@ -44,14 +51,13 @@ class Class_ extends Declaration
     /**
      * Implements one or more interfaces.
      *
-     * @param Name|string $interface Name of interface to implement
-     * @param Name|string $...       More interfaces to implement
+     * @param Name|string ...$interfaces Names of interfaces to implement
      *
      * @return $this The builder instance (for fluid interface)
      */
-    public function implement() {
-        foreach (func_get_args() as $interface) {
-            $this->implements[] = $this->normalizeName($interface);
+    public function implement(...$interfaces) {
+        foreach ($interfaces as $interface) {
+            $this->implements[] = BuilderHelpers::normalizeName($interface);
         }
 
         return $this;
@@ -63,7 +69,7 @@ class Class_ extends Declaration
      * @return $this The builder instance (for fluid interface)
      */
     public function makeAbstract() {
-        $this->setModifier(Stmt\Class_::MODIFIER_ABSTRACT);
+        $this->flags = BuilderHelpers::addClassModifier($this->flags, Modifiers::ABSTRACT);
 
         return $this;
     }
@@ -74,7 +80,18 @@ class Class_ extends Declaration
      * @return $this The builder instance (for fluid interface)
      */
     public function makeFinal() {
-        $this->setModifier(Stmt\Class_::MODIFIER_FINAL);
+        $this->flags = BuilderHelpers::addClassModifier($this->flags, Modifiers::FINAL);
+
+        return $this;
+    }
+
+    /**
+     * Makes the class readonly.
+     *
+     * @return $this The builder instance (for fluid interface)
+     */
+    public function makeReadonly() {
+        $this->flags = BuilderHelpers::addClassModifier($this->flags, Modifiers::READONLY);
 
         return $this;
     }
@@ -87,21 +104,32 @@ class Class_ extends Declaration
      * @return $this The builder instance (for fluid interface)
      */
     public function addStmt($stmt) {
-        $stmt = $this->normalizeNode($stmt);
+        $stmt = BuilderHelpers::normalizeNode($stmt);
 
-        $targets = array(
-            'Stmt_TraitUse'    => &$this->uses,
-            'Stmt_ClassConst'  => &$this->constants,
-            'Stmt_Property'    => &$this->properties,
-            'Stmt_ClassMethod' => &$this->methods,
-        );
-
-        $type = $stmt->getType();
-        if (!isset($targets[$type])) {
-            throw new \LogicException(sprintf('Unexpected node of type "%s"', $type));
+        if ($stmt instanceof Stmt\Property) {
+            $this->properties[] = $stmt;
+        } elseif ($stmt instanceof Stmt\ClassMethod) {
+            $this->methods[] = $stmt;
+        } elseif ($stmt instanceof Stmt\TraitUse) {
+            $this->uses[] = $stmt;
+        } elseif ($stmt instanceof Stmt\ClassConst) {
+            $this->constants[] = $stmt;
+        } else {
+            throw new \LogicException(sprintf('Unexpected node of type "%s"', $stmt->getType()));
         }
 
-        $targets[$type][] = $stmt;
+        return $this;
+    }
+
+    /**
+     * Adds an attribute group.
+     *
+     * @param Node\Attribute|Node\AttributeGroup $attribute
+     *
+     * @return $this The builder instance (for fluid interface)
+     */
+    public function addAttribute($attribute) {
+        $this->attributeGroups[] = BuilderHelpers::normalizeAttribute($attribute);
 
         return $this;
     }
@@ -111,12 +139,13 @@ class Class_ extends Declaration
      *
      * @return Stmt\Class_ The built class node
      */
-    public function getNode() {
-        return new Stmt\Class_($this->name, array(
-            'type' => $this->type,
+    public function getNode(): PhpParser\Node {
+        return new Stmt\Class_($this->name, [
+            'flags' => $this->flags,
             'extends' => $this->extends,
             'implements' => $this->implements,
             'stmts' => array_merge($this->uses, $this->constants, $this->properties, $this->methods),
-        ), $this->attributes);
+            'attrGroups' => $this->attributeGroups,
+        ], $this->attributes);
     }
-}
+}

lib/PhpParser/Builder/Declaration.php

@@ -1,21 +1,27 @@
-<?php
+<?php declare(strict_types=1);
 
 namespace PhpParser\Builder;
 
 use PhpParser;
-use PhpParser\Node;
-use PhpParser\Node\Stmt;
+use PhpParser\BuilderHelpers;
 
-abstract class Declaration extends PhpParser\BuilderAbstract
-{
-    protected $attributes = array();
+abstract class Declaration implements PhpParser\Builder {
+    /** @var array<string, mixed> */
+    protected array $attributes = [];
 
+    /**
+     * Adds a statement.
+     *
+     * @param PhpParser\Node\Stmt|PhpParser\Builder $stmt The statement to add
+     *
+     * @return $this The builder instance (for fluid interface)
+     */
     abstract public function addStmt($stmt);
 
     /**
      * Adds multiple statements.
      *
-     * @param array $stmts The statements to add
+     * @param (PhpParser\Node\Stmt|PhpParser\Builder)[] $stmts The statements to add
      *
      * @return $this The builder instance (for fluid interface)
      */
@@ -35,10 +41,10 @@ abstract class Declaration extends PhpParser\BuilderAbstract
      * @return $this The builder instance (for fluid interface)
      */
     public function setDocComment($docComment) {
-        $this->attributes['comments'] = array(
-            $this->normalizeDocComment($docComment)
-        );
+        $this->attributes['comments'] = [
+            BuilderHelpers::normalizeDocComment($docComment)
+        ];
 
         return $this;
     }
-}
+}

lib/PhpParser/Builder/EnumCase.php

@@ -0,0 +1,87 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhpParser\Builder;
+
+use PhpParser;
+use PhpParser\BuilderHelpers;
+use PhpParser\Node;
+use PhpParser\Node\Identifier;
+use PhpParser\Node\Stmt;
+
+class EnumCase implements PhpParser\Builder {
+    /** @var Identifier|string */
+    protected $name;
+    /** @var ?Node\Expr */
+    protected ?Node\Expr $value = null;
+    /** @var array<string, mixed> */
+    protected array $attributes = [];
+
+    /** @var list<Node\AttributeGroup> */
+    protected array $attributeGroups = [];
+
+    /**
+     * Creates an enum case builder.
+     *
+     * @param string|Identifier $name Name
+     */
+    public function __construct($name) {
+        $this->name = $name;
+    }
+
+    /**
+     * Sets the value.
+     *
+     * @param Node\Expr|string|int $value
+     *
+     * @return $this
+     */
+    public function setValue($value) {
+        $this->value = BuilderHelpers::normalizeValue($value);
+
+        return $this;
+    }
+
+    /**
+     * Sets doc comment for the constant.
+     *
+     * @param PhpParser\Comment\Doc|string $docComment Doc comment to set
+     *
+     * @return $this The builder instance (for fluid interface)
+     */
+    public function setDocComment($docComment) {
+        $this->attributes = [
+            'comments' => [BuilderHelpers::normalizeDocComment($docComment)]
+        ];
+
+        return $this;
+    }
+
+    /**
+     * Adds an attribute group.
+     *
+     * @param Node\Attribute|Node\AttributeGroup $attribute
+     *
+     * @return $this The builder instance (for fluid interface)
+     */
+    public function addAttribute($attribute) {
+        $this->attributeGroups[] = BuilderHelpers::normalizeAttribute($attribute);
+
+        return $this;
+    }
+
+    /**
+     * Returns the built enum case node.
+     *
+     * @return Stmt\EnumCase The built constant node
+     */
+    public function getNode(): PhpParser\Node {
+        return new Stmt\EnumCase(
+            $this->name,
+            $this->value,
+            $this->attributeGroups,
+            $this->attributes
+        );
+    }
+}

lib/PhpParser/Builder/Enum_.php

@@ -0,0 +1,116 @@
+<?php declare(strict_types=1);
+
+namespace PhpParser\Builder;
+
+use PhpParser;
+use PhpParser\BuilderHelpers;
+use PhpParser\Node;
+use PhpParser\Node\Identifier;
+use PhpParser\Node\Name;
+use PhpParser\Node\Stmt;
+
+class Enum_ extends Declaration {
+    protected string $name;
+    protected ?Identifier $scalarType = null;
+    /** @var list<Name> */
+    protected array $implements = [];
+    /** @var list<Stmt\TraitUse> */
+    protected array $uses = [];
+    /** @var list<Stmt\EnumCase> */
+    protected array $enumCases = [];
+    /** @var list<Stmt\ClassConst> */
+    protected array $constants = [];
+    /** @var list<Stmt\ClassMethod> */
+    protected array $methods = [];
+    /** @var list<Node\AttributeGroup> */
+    protected array $attributeGroups = [];
+
+    /**
+     * Creates an enum builder.
+     *
+     * @param string $name Name of the enum
+     */
+    public function __construct(string $name) {
+        $this->name = $name;
+    }
+
+    /**
+     * Sets the scalar type.
+     *
+     * @param string|Identifier $scalarType
+     *
+     * @return $this
+     */
+    public function setScalarType($scalarType) {
+        $this->scalarType = BuilderHelpers::normalizeType($scalarType);
+
+        return $this;
+    }
+
+    /**
+     * Implements one or more interfaces.
+     *
+     * @param Name|string ...$interfaces Names of interfaces to implement
+     *
+     * @return $this The builder instance (for fluid interface)
+     */
+    public function implement(...$interfaces) {
+        foreach ($interfaces as $interface) {
+            $this->implements[] = BuilderHelpers::normalizeName($interface);
+        }
+
+        return $this;
+    }
+
+    /**
+     * Adds a statement.
+     *
+     * @param Stmt|PhpParser\Builder $stmt The statement to add
+     *
+     * @return $this The builder instance (for fluid interface)
+     */
+    public function addStmt($stmt) {
+        $stmt = BuilderHelpers::normalizeNode($stmt);
+
+        if ($stmt instanceof Stmt\EnumCase) {
+            $this->enumCases[] = $stmt;
+        } elseif ($stmt instanceof Stmt\ClassMethod) {
+            $this->methods[] = $stmt;
+        } elseif ($stmt instanceof Stmt\TraitUse) {
+            $this->uses[] = $stmt;
+        } elseif ($stmt instanceof Stmt\ClassConst) {
+            $this->constants[] = $stmt;
+        } else {
+            throw new \LogicException(sprintf('Unexpected node of type "%s"', $stmt->getType()));
+        }
+
+        return $this;
+    }
+
+    /**
+     * Adds an attribute group.
+     *
+     * @param Node\Attribute|Node\AttributeGroup $attribute
+     *
+     * @return $this The builder instance (for fluid interface)
+     */
+    public function addAttribute($attribute) {
+        $this->attributeGroups[] = BuilderHelpers::normalizeAttribute($attribute);
+
+        return $this;
+    }
+
+    /**
+     * Returns the built class node.
+     *
+     * @return Stmt\Enum_ The built enum node
+     */
+    public function getNode(): PhpParser\Node {
+        return new Stmt\Enum_($this->name, [
+            'scalarType' => $this->scalarType,
+            'implements' => $this->implements,
+            'stmts' => array_merge($this->uses, $this->enumCases, $this->constants, $this->methods),
+            'attrGroups' => $this->attributeGroups,
+        ], $this->attributes);
+    }
+}

lib/PhpParser/Builder/FunctionLike.php

@@ -1,15 +1,17 @@
-<?php
+<?php declare(strict_types=1);
 
 namespace PhpParser\Builder;
 
-use PhpParser;
+use PhpParser\BuilderHelpers;
 use PhpParser\Node;
-use PhpParser\Node\Stmt;
 
-abstract class FunctionLike extends Declaration
-{
-    protected $returnByRef = false;
-    protected $params = array();
+abstract class FunctionLike extends Declaration {
+    protected bool $returnByRef = false;
+    /** @var Node\Param[] */
+    protected array $params = [];
+
+    /** @var Node\Identifier|Node\Name|Node\ComplexType|null */
+    protected ?Node $returnType = null;
 
     /**
      * Make the function return by reference.
@@ -30,7 +32,7 @@ abstract class FunctionLike extends Declaration
      * @return $this The builder instance (for fluid interface)
      */
     public function addParam($param) {
-        $param = $this->normalizeNode($param);
+        $param = BuilderHelpers::normalizeNode($param);
 
         if (!$param instanceof Node\Param) {
             throw new \LogicException(sprintf('Expected parameter node, got "%s"', $param->getType()));
@@ -44,7 +46,7 @@ abstract class FunctionLike extends Declaration
     /**
      * Adds multiple parameters.
      *
-     * @param array $params The parameters to add
+     * @param (Node\Param|Param)[] $params The parameters to add
      *
      * @return $this The builder instance (for fluid interface)
      */
@@ -55,4 +57,17 @@ abstract class FunctionLike extends Declaration
 
         return $this;
     }
-}
+
+    /**
+     * Sets the return type for PHP 7.
+     *
+     * @param string|Node\Name|Node\Identifier|Node\ComplexType $type
+     *
+     * @return $this The builder instance (for fluid interface)
+     */
+    public function setReturnType($type) {
+        $this->returnType = BuilderHelpers::normalizeType($type);
+
+        return $this;
+    }
+}

lib/PhpParser/Builder/Function_.php

@@ -1,22 +1,26 @@
-<?php
+<?php declare(strict_types=1);
 
 namespace PhpParser\Builder;
 
 use PhpParser;
+use PhpParser\BuilderHelpers;
 use PhpParser\Node;
 use PhpParser\Node\Stmt;
 
-class Function_ extends FunctionLike
-{
-    protected $name;
-    protected $stmts = array();
+class Function_ extends FunctionLike {
+    protected string $name;
+    /** @var list<Stmt> */
+    protected array $stmts = [];
+
+    /** @var list<Node\AttributeGroup> */
+    protected array $attributeGroups = [];
 
     /**
      * Creates a function builder.
      *
      * @param string $name Name of the function
      */
-    public function __construct($name) {
+    public function __construct(string $name) {
         $this->name = $name;
     }
 
@@ -28,7 +32,20 @@ class Function_ extends FunctionLike
      * @return $this The builder instance (for fluid interface)
      */
     public function addStmt($stmt) {
-        $this->stmts[] = $this->normalizeNode($stmt);
+        $this->stmts[] = BuilderHelpers::normalizeStmt($stmt);
+
+        return $this;
+    }
+
+    /**
+     * Adds an attribute group.
+     *
+     * @param Node\Attribute|Node\AttributeGroup $attribute
+     *
+     * @return $this The builder instance (for fluid interface)
+     */
+    public function addAttribute($attribute) {
+        $this->attributeGroups[] = BuilderHelpers::normalizeAttribute($attribute);
 
         return $this;
     }
@@ -38,11 +55,13 @@ class Function_ extends FunctionLike
      *
      * @return Stmt\Function_ The built function node
      */
-    public function getNode() {
-        return new Stmt\Function_($this->name, array(
-            'byRef'  => $this->returnByRef,
-            'params' => $this->params,
-            'stmts'  => $this->stmts,
-        ), $this->attributes);
+    public function getNode(): Node {
+        return new Stmt\Function_($this->name, [
+            'byRef'      => $this->returnByRef,
+            'params'     => $this->params,
+            'returnType' => $this->returnType,
+            'stmts'      => $this->stmts,
+            'attrGroups' => $this->attributeGroups,
+        ], $this->attributes);
     }
-}
+}

lib/PhpParser/Builder/Interface_.php

@@ -1,38 +1,43 @@
-<?php
+<?php declare(strict_types=1);
 
 namespace PhpParser\Builder;
 
 use PhpParser;
+use PhpParser\BuilderHelpers;
+use PhpParser\Node;
 use PhpParser\Node\Name;
 use PhpParser\Node\Stmt;
 
-class Interface_ extends Declaration
-{
-    protected $name;
-    protected $extends = array();
-    protected $constants = array();
-    protected $methods = array();
+class Interface_ extends Declaration {
+    protected string $name;
+    /** @var list<Name> */
+    protected array $extends = [];
+    /** @var list<Stmt\ClassConst> */
+    protected array $constants = [];
+    /** @var list<Stmt\ClassMethod> */
+    protected array $methods = [];
+    /** @var list<Node\AttributeGroup> */
+    protected array $attributeGroups = [];
 
     /**
      * Creates an interface builder.
      *
      * @param string $name Name of the interface
      */
-    public function __construct($name) {
+    public function __construct(string $name) {
         $this->name = $name;
     }
 
     /**
      * Extends one or more interfaces.
      *
-     * @param Name|string $interface Name of interface to extend
-     * @param Name|string $...       More interfaces to extend
+     * @param Name|string ...$interfaces Names of interfaces to extend
      *
      * @return $this The builder instance (for fluid interface)
      */
-    public function extend() {
-        foreach (func_get_args() as $interface) {
-            $this->extends[] = $this->normalizeName($interface);
+    public function extend(...$interfaces) {
+        foreach ($interfaces as $interface) {
+            $this->extends[] = BuilderHelpers::normalizeName($interface);
         }
 
         return $this;
@@ -46,36 +51,44 @@ class Interface_ extends Declaration
      * @return $this The builder instance (for fluid interface)
      */
     public function addStmt($stmt) {
-        $stmt = $this->normalizeNode($stmt);
+        $stmt = BuilderHelpers::normalizeNode($stmt);
 
-        $type = $stmt->getType();
-        switch ($type) {
-            case 'Stmt_ClassConst':
-                $this->constants[] = $stmt;
-                break;
-
-            case 'Stmt_ClassMethod':
-                // we erase all statements in the body of an interface method
-                $stmt->stmts = null;
-                $this->methods[] = $stmt;
-                break;
-
-            default:
-                throw new \LogicException(sprintf('Unexpected node of type "%s"', $type));
+        if ($stmt instanceof Stmt\ClassConst) {
+            $this->constants[] = $stmt;
+        } elseif ($stmt instanceof Stmt\ClassMethod) {
+            // we erase all statements in the body of an interface method
+            $stmt->stmts = null;
+            $this->methods[] = $stmt;
+        } else {
+            throw new \LogicException(sprintf('Unexpected node of type "%s"', $stmt->getType()));
         }
 
         return $this;
     }
 
+    /**
+     * Adds an attribute group.
+     *
+     * @param Node\Attribute|Node\AttributeGroup $attribute
+     *
+     * @return $this The builder instance (for fluid interface)
+     */
+    public function addAttribute($attribute) {
+        $this->attributeGroups[] = BuilderHelpers::normalizeAttribute($attribute);
+
+        return $this;
+    }
+
     /**
      * Returns the built interface node.
      *
      * @return Stmt\Interface_ The built interface node
      */
-    public function getNode() {
-        return new Stmt\Interface_($this->name, array(
+    public function getNode(): PhpParser\Node {
+        return new Stmt\Interface_($this->name, [
             'extends' => $this->extends,
             'stmts' => array_merge($this->constants, $this->methods),
-        ), $this->attributes);
+            'attrGroups' => $this->attributeGroups,
+        ], $this->attributes);
     }
-}
+}

lib/PhpParser/Builder/Method.php

@@ -1,23 +1,30 @@
-<?php
+<?php declare(strict_types=1);
 
 namespace PhpParser\Builder;
 
 use PhpParser;
+use PhpParser\BuilderHelpers;
+use PhpParser\Modifiers;
 use PhpParser\Node;
 use PhpParser\Node\Stmt;
 
-class Method extends FunctionLike
-{
-    protected $name;
-    protected $type = 0;
-    protected $stmts = array();
+class Method extends FunctionLike {
+    protected string $name;
+
+    protected int $flags = 0;
+
+    /** @var list<Stmt>|null */
+    protected ?array $stmts = [];
+
+    /** @var list<Node\AttributeGroup> */
+    protected array $attributeGroups = [];
 
     /**
      * Creates a method builder.
      *
      * @param string $name Name of the method
      */
-    public function __construct($name) {
+    public function __construct(string $name) {
         $this->name = $name;
     }
 
@@ -27,7 +34,7 @@ class Method extends FunctionLike
      * @return $this The builder instance (for fluid interface)
      */
     public function makePublic() {
-        $this->setModifier(Stmt\Class_::MODIFIER_PUBLIC);
+        $this->flags = BuilderHelpers::addModifier($this->flags, Modifiers::PUBLIC);
 
         return $this;
     }
@@ -38,7 +45,7 @@ class Method extends FunctionLike
      * @return $this The builder instance (for fluid interface)
      */
     public function makeProtected() {
-        $this->setModifier(Stmt\Class_::MODIFIER_PROTECTED);
+        $this->flags = BuilderHelpers::addModifier($this->flags, Modifiers::PROTECTED);
 
         return $this;
     }
@@ -49,7 +56,7 @@ class Method extends FunctionLike
      * @return $this The builder instance (for fluid interface)
      */
     public function makePrivate() {
-        $this->setModifier(Stmt\Class_::MODIFIER_PRIVATE);
+        $this->flags = BuilderHelpers::addModifier($this->flags, Modifiers::PRIVATE);
 
         return $this;
     }
@@ -60,7 +67,7 @@ class Method extends FunctionLike
      * @return $this The builder instance (for fluid interface)
      */
     public function makeStatic() {
-        $this->setModifier(Stmt\Class_::MODIFIER_STATIC);
+        $this->flags = BuilderHelpers::addModifier($this->flags, Modifiers::STATIC);
 
         return $this;
     }
@@ -75,7 +82,7 @@ class Method extends FunctionLike
             throw new \LogicException('Cannot make method with statements abstract');
         }
 
-        $this->setModifier(Stmt\Class_::MODIFIER_ABSTRACT);
+        $this->flags = BuilderHelpers::addModifier($this->flags, Modifiers::ABSTRACT);
         $this->stmts = null; // abstract methods don't have statements
 
         return $this;
@@ -87,7 +94,7 @@ class Method extends FunctionLike
      * @return $this The builder instance (for fluid interface)
      */
     public function makeFinal() {
-        $this->setModifier(Stmt\Class_::MODIFIER_FINAL);
+        $this->flags = BuilderHelpers::addModifier($this->flags, Modifiers::FINAL);
 
         return $this;
     }
@@ -104,7 +111,20 @@ class Method extends FunctionLike
             throw new \LogicException('Cannot add statements to an abstract method');
         }
 
-        $this->stmts[] = $this->normalizeNode($stmt);
+        $this->stmts[] = BuilderHelpers::normalizeStmt($stmt);
+
+        return $this;
+    }
+
+    /**
+     * Adds an attribute group.
+     *
+     * @param Node\Attribute|Node\AttributeGroup $attribute
+     *
+     * @return $this The builder instance (for fluid interface)
+     */
+    public function addAttribute($attribute) {
+        $this->attributeGroups[] = BuilderHelpers::normalizeAttribute($attribute);
 
         return $this;
     }
@@ -114,12 +134,14 @@ class Method extends FunctionLike
      *
      * @return Stmt\ClassMethod The built method node
      */
-    public function getNode() {
-        return new Stmt\ClassMethod($this->name, array(
-            'type'   => $this->type,
-            'byRef'  => $this->returnByRef,
-            'params' => $this->params,
-            'stmts'  => $this->stmts,
-        ), $this->attributes);
+    public function getNode(): Node {
+        return new Stmt\ClassMethod($this->name, [
+            'flags'      => $this->flags,
+            'byRef'      => $this->returnByRef,
+            'params'     => $this->params,
+            'returnType' => $this->returnType,
+            'stmts'      => $this->stmts,
+            'attrGroups' => $this->attributeGroups,
+        ], $this->attributes);
     }
 }

lib/PhpParser/Builder/Namespace_.php

@@ -1,15 +1,16 @@
-<?php
+<?php declare(strict_types=1);
 
 namespace PhpParser\Builder;
 
 use PhpParser;
+use PhpParser\BuilderHelpers;
 use PhpParser\Node;
 use PhpParser\Node\Stmt;
 
-class Namespace_ extends PhpParser\BuilderAbstract
-{
-    private $name;
-    private $stmts = array();
+class Namespace_ extends Declaration {
+    private ?Node\Name $name;
+    /** @var Stmt[] */
+    private array $stmts = [];
 
     /**
      * Creates a namespace builder.
@@ -17,7 +18,7 @@ class Namespace_ extends PhpParser\BuilderAbstract
      * @param Node\Name|string|null $name Name of the namespace
      */
     public function __construct($name) {
-        $this->name = null !== $name ? $this->normalizeName($name) : null;
+        $this->name = null !== $name ? BuilderHelpers::normalizeName($name) : null;
     }
 
     /**
@@ -28,22 +29,7 @@ class Namespace_ extends PhpParser\BuilderAbstract
      * @return $this The builder instance (for fluid interface)
      */
     public function addStmt($stmt) {
-        $this->stmts[] = $this->normalizeNode($stmt);
-
-        return $this;
-    }
-
-    /**
-     * Adds multiple statements.
-     *
-     * @param array $stmts The statements to add
-     *
-     * @return $this The builder instance (for fluid interface)
-     */
-    public function addStmts(array $stmts) {
-        foreach ($stmts as $stmt) {
-            $this->addStmt($stmt);
-        }
+        $this->stmts[] = BuilderHelpers::normalizeStmt($stmt);
 
         return $this;
     }
@@ -51,9 +37,9 @@ class Namespace_ extends PhpParser\BuilderAbstract
     /**
      * Returns the built node.
      *
-     * @return Node The built node
+     * @return Stmt\Namespace_ The built node
      */
-    public function getNode() {
-        return new Stmt\Namespace_($this->name, $this->stmts);
+    public function getNode(): Node {
+        return new Stmt\Namespace_($this->name, $this->stmts, $this->attributes);
     }
 }

lib/PhpParser/Builder/Param.php

@@ -1,24 +1,29 @@
-<?php
+<?php declare(strict_types=1);
 
 namespace PhpParser\Builder;
 
 use PhpParser;
+use PhpParser\BuilderHelpers;
+use PhpParser\Modifiers;
 use PhpParser\Node;
 
-class Param extends PhpParser\BuilderAbstract
-{
-    protected $name;
-
-    protected $default = null;
-    protected $type = null;
-    protected $byRef = false;
+class Param implements PhpParser\Builder {
+    protected string $name;
+    protected ?Node\Expr $default = null;
+    /** @var Node\Identifier|Node\Name|Node\ComplexType|null */
+    protected ?Node $type = null;
+    protected bool $byRef = false;
+    protected int $flags = 0;
+    protected bool $variadic = false;
+    /** @var list<Node\AttributeGroup> */
+    protected array $attributeGroups = [];
 
     /**
      * Creates a parameter builder.
      *
      * @param string $name Name of the parameter
      */
-    public function __construct($name) {
+    public function __construct(string $name) {
         $this->name = $name;
     }
 
@@ -30,23 +35,22 @@ class Param extends PhpParser\BuilderAbstract
      * @return $this The builder instance (for fluid interface)
      */
     public function setDefault($value) {
-        $this->default = $this->normalizeValue($value);
+        $this->default = BuilderHelpers::normalizeValue($value);
 
         return $this;
     }
 
     /**
-     * Sets type hint for the parameter.
+     * Sets type for the parameter.
      *
-     * @param string|Node\Name $type Type hint to use
+     * @param string|Node\Name|Node\Identifier|Node\ComplexType $type Parameter type
      *
      * @return $this The builder instance (for fluid interface)
      */
-    public function setTypeHint($type) {
-        if ($type === 'array' || $type === 'callable') {
-            $this->type = $type;
-        } else {
-            $this->type = $this->normalizeName($type);
+    public function setType($type) {
+        $this->type = BuilderHelpers::normalizeType($type);
+        if ($this->type == 'void') {
+            throw new \LogicException('Parameter type cannot be void');
         }
 
         return $this;
@@ -63,14 +67,83 @@ class Param extends PhpParser\BuilderAbstract
         return $this;
     }
 
+    /**
+     * Make the parameter variadic
+     *
+     * @return $this The builder instance (for fluid interface)
+     */
+    public function makeVariadic() {
+        $this->variadic = true;
+
+        return $this;
+    }
+
+    /**
+     * Makes the (promoted) parameter public.
+     *
+     * @return $this The builder instance (for fluid interface)
+     */
+    public function makePublic() {
+        $this->flags = BuilderHelpers::addModifier($this->flags, Modifiers::PUBLIC);
+
+        return $this;
+    }
+
+    /**
+     * Makes the (promoted) parameter protected.
+     *
+     * @return $this The builder instance (for fluid interface)
+     */
+    public function makeProtected() {
+        $this->flags = BuilderHelpers::addModifier($this->flags, Modifiers::PROTECTED);
+
+        return $this;
+    }
+
+    /**
+     * Makes the (promoted) parameter private.
+     *
+     * @return $this The builder instance (for fluid interface)
+     */
+    public function makePrivate() {
+        $this->flags = BuilderHelpers::addModifier($this->flags, Modifiers::PRIVATE);
+
+        return $this;
+    }
+
+    /**
+     * Makes the (promoted) parameter readonly.
+     *
+     * @return $this The builder instance (for fluid interface)
+     */
+    public function makeReadonly() {
+        $this->flags = BuilderHelpers::addModifier($this->flags, Modifiers::READONLY);
+
+        return $this;
+    }
+
+    /**
+     * Adds an attribute group.
+     *
+     * @param Node\Attribute|Node\AttributeGroup $attribute
+     *
+     * @return $this The builder instance (for fluid interface)
+     */
+    public function addAttribute($attribute) {
+        $this->attributeGroups[] = BuilderHelpers::normalizeAttribute($attribute);
+
+        return $this;
+    }
+
     /**
      * Returns the built parameter node.
      *
      * @return Node\Param The built parameter node
      */
-    public function getNode() {
+    public function getNode(): Node {
         return new Node\Param(
-            $this->name, $this->default, $this->type, $this->byRef
+            new Node\Expr\Variable($this->name),
+            $this->default, $this->type, $this->byRef, $this->variadic, [], $this->flags, $this->attributeGroups
         );
     }
-}
+}

lib/PhpParser/Builder/Property.php

@@ -1,24 +1,35 @@
-<?php
+<?php declare(strict_types=1);
 
 namespace PhpParser\Builder;
 
 use PhpParser;
+use PhpParser\BuilderHelpers;
+use PhpParser\Modifiers;
+use PhpParser\Node;
+use PhpParser\Node\Identifier;
+use PhpParser\Node\Name;
 use PhpParser\Node\Stmt;
+use PhpParser\Node\ComplexType;
 
-class Property extends PhpParser\BuilderAbstract
-{
-    protected $name;
+class Property implements PhpParser\Builder {
+    protected string $name;
 
-    protected $type = 0;
-    protected $default = null;
-    protected $attributes = array();
+    protected int $flags = 0;
+
+    protected ?Node\Expr $default = null;
+    /** @var array<string, mixed> */
+    protected array $attributes = [];
+    /** @var null|Identifier|Name|ComplexType */
+    protected ?Node $type = null;
+    /** @var list<Node\AttributeGroup> */
+    protected array $attributeGroups = [];
 
     /**
      * Creates a property builder.
      *
      * @param string $name Name of the property
      */
-    public function __construct($name) {
+    public function __construct(string $name) {
         $this->name = $name;
     }
 
@@ -28,7 +39,7 @@ class Property extends PhpParser\BuilderAbstract
      * @return $this The builder instance (for fluid interface)
      */
     public function makePublic() {
-        $this->setModifier(Stmt\Class_::MODIFIER_PUBLIC);
+        $this->flags = BuilderHelpers::addModifier($this->flags, Modifiers::PUBLIC);
 
         return $this;
     }
@@ -39,7 +50,7 @@ class Property extends PhpParser\BuilderAbstract
      * @return $this The builder instance (for fluid interface)
      */
     public function makeProtected() {
-        $this->setModifier(Stmt\Class_::MODIFIER_PROTECTED);
+        $this->flags = BuilderHelpers::addModifier($this->flags, Modifiers::PROTECTED);
 
         return $this;
     }
@@ -50,7 +61,7 @@ class Property extends PhpParser\BuilderAbstract
      * @return $this The builder instance (for fluid interface)
      */
     public function makePrivate() {
-        $this->setModifier(Stmt\Class_::MODIFIER_PRIVATE);
+        $this->flags = BuilderHelpers::addModifier($this->flags, Modifiers::PRIVATE);
 
         return $this;
     }
@@ -61,7 +72,18 @@ class Property extends PhpParser\BuilderAbstract
      * @return $this The builder instance (for fluid interface)
      */
     public function makeStatic() {
-        $this->setModifier(Stmt\Class_::MODIFIER_STATIC);
+        $this->flags = BuilderHelpers::addModifier($this->flags, Modifiers::STATIC);
+
+        return $this;
+    }
+
+    /**
+     * Makes the property readonly.
+     *
+     * @return $this The builder instance (for fluid interface)
+     */
+    public function makeReadonly() {
+        $this->flags = BuilderHelpers::addModifier($this->flags, Modifiers::READONLY);
 
         return $this;
     }
@@ -74,7 +96,7 @@ class Property extends PhpParser\BuilderAbstract
      * @return $this The builder instance (for fluid interface)
      */
     public function setDefault($value) {
-        $this->default = $this->normalizeValue($value);
+        $this->default = BuilderHelpers::normalizeValue($value);
 
         return $this;
     }
@@ -87,9 +109,35 @@ class Property extends PhpParser\BuilderAbstract
      * @return $this The builder instance (for fluid interface)
      */
     public function setDocComment($docComment) {
-        $this->attributes = array(
-            'comments' => array($this->normalizeDocComment($docComment))
-        );
+        $this->attributes = [
+            'comments' => [BuilderHelpers::normalizeDocComment($docComment)]
+        ];
+
+        return $this;
+    }
+
+    /**
+     * Sets the property type for PHP 7.4+.
+     *
+     * @param string|Name|Identifier|ComplexType $type
+     *
+     * @return $this
+     */
+    public function setType($type) {
+        $this->type = BuilderHelpers::normalizeType($type);
+
+        return $this;
+    }
+
+    /**
+     * Adds an attribute group.
+     *
+     * @param Node\Attribute|Node\AttributeGroup $attribute
+     *
+     * @return $this The builder instance (for fluid interface)
+     */
+    public function addAttribute($attribute) {
+        $this->attributeGroups[] = BuilderHelpers::normalizeAttribute($attribute);
 
         return $this;
     }
@@ -99,13 +147,15 @@ class Property extends PhpParser\BuilderAbstract
      *
      * @return Stmt\Property The built property node
      */
-    public function getNode() {
+    public function getNode(): PhpParser\Node {
         return new Stmt\Property(
-            $this->type !== 0 ? $this->type : Stmt\Class_::MODIFIER_PUBLIC,
-            array(
-                new Stmt\PropertyProperty($this->name, $this->default)
-            ),
-            $this->attributes
+            $this->flags !== 0 ? $this->flags : Modifiers::PUBLIC,
+            [
+                new Node\PropertyItem($this->name, $this->default)
+            ],
+            $this->attributes,
+            $this->type,
+            $this->attributeGroups
         );
     }
-}
+}

lib/PhpParser/Builder/TraitUse.php

@@ -0,0 +1,65 @@
+<?php declare(strict_types=1);
+
+namespace PhpParser\Builder;
+
+use PhpParser\Builder;
+use PhpParser\BuilderHelpers;
+use PhpParser\Node;
+use PhpParser\Node\Stmt;
+
+class TraitUse implements Builder {
+    /** @var Node\Name[] */
+    protected array $traits = [];
+    /** @var Stmt\TraitUseAdaptation[] */
+    protected array $adaptations = [];
+
+    /**
+     * Creates a trait use builder.
+     *
+     * @param Node\Name|string ...$traits Names of used traits
+     */
+    public function __construct(...$traits) {
+        foreach ($traits as $trait) {
+            $this->and($trait);
+        }
+    }
+
+    /**
+     * Adds used trait.
+     *
+     * @param Node\Name|string $trait Trait name
+     *
+     * @return $this The builder instance (for fluid interface)
+     */
+    public function and($trait) {
+        $this->traits[] = BuilderHelpers::normalizeName($trait);
+        return $this;
+    }
+
+    /**
+     * Adds trait adaptation.
+     *
+     * @param Stmt\TraitUseAdaptation|Builder\TraitUseAdaptation $adaptation Trait adaptation
+     *
+     * @return $this The builder instance (for fluid interface)
+     */
+    public function with($adaptation) {
+        $adaptation = BuilderHelpers::normalizeNode($adaptation);
+
+        if (!$adaptation instanceof Stmt\TraitUseAdaptation) {
+            throw new \LogicException('Adaptation must have type TraitUseAdaptation');
+        }
+
+        $this->adaptations[] = $adaptation;
+        return $this;
+    }
+
+    /**
+     * Returns the built node.
+     *
+     * @return Node The built node
+     */
+    public function getNode(): Node {
+        return new Stmt\TraitUse($this->traits, $this->adaptations);
+    }
+}

lib/PhpParser/Builder/TraitUseAdaptation.php

@@ -0,0 +1,145 @@
+<?php declare(strict_types=1);
+
+namespace PhpParser\Builder;
+
+use PhpParser\Builder;
+use PhpParser\BuilderHelpers;
+use PhpParser\Modifiers;
+use PhpParser\Node;
+use PhpParser\Node\Stmt;
+
+class TraitUseAdaptation implements Builder {
+    private const TYPE_UNDEFINED  = 0;
+    private const TYPE_ALIAS      = 1;
+    private const TYPE_PRECEDENCE = 2;
+
+    protected int $type;
+    protected ?Node\Name $trait;
+    protected Node\Identifier $method;
+    protected ?int $modifier = null;
+    protected ?Node\Identifier $alias = null;
+    /** @var Node\Name[] */
+    protected array $insteadof = [];
+
+    /**
+     * Creates a trait use adaptation builder.
+     *
+     * @param Node\Name|string|null $trait Name of adapted trait
+     * @param Node\Identifier|string $method Name of adapted method
+     */
+    public function __construct($trait, $method) {
+        $this->type = self::TYPE_UNDEFINED;
+
+        $this->trait = is_null($trait) ? null : BuilderHelpers::normalizeName($trait);
+        $this->method = BuilderHelpers::normalizeIdentifier($method);
+    }
+
+    /**
+     * Sets alias of method.
+     *
+     * @param Node\Identifier|string $alias Alias for adapted method
+     *
+     * @return $this The builder instance (for fluid interface)
+     */
+    public function as($alias) {
+        if ($this->type === self::TYPE_UNDEFINED) {
+            $this->type = self::TYPE_ALIAS;
+        }
+
+        if ($this->type !== self::TYPE_ALIAS) {
+            throw new \LogicException('Cannot set alias for not alias adaptation buider');
+        }
+
+        $this->alias = BuilderHelpers::normalizeIdentifier($alias);
+        return $this;
+    }
+
+    /**
+     * Sets adapted method public.
+     *
+     * @return $this The builder instance (for fluid interface)
+     */
+    public function makePublic() {
+        $this->setModifier(Modifiers::PUBLIC);
+        return $this;
+    }
+
+    /**
+     * Sets adapted method protected.
+     *
+     * @return $this The builder instance (for fluid interface)
+     */
+    public function makeProtected() {
+        $this->setModifier(Modifiers::PROTECTED);
+        return $this;
+    }
+
+    /**
+     * Sets adapted method private.
+     *
+     * @return $this The builder instance (for fluid interface)
+     */
+    public function makePrivate() {
+        $this->setModifier(Modifiers::PRIVATE);
+        return $this;
+    }
+
+    /**
+     * Adds overwritten traits.
+     *
+     * @param Node\Name|string ...$traits Traits for overwrite
+     *
+     * @return $this The builder instance (for fluid interface)
+     */
+    public function insteadof(...$traits) {
+        if ($this->type === self::TYPE_UNDEFINED) {
+            if (is_null($this->trait)) {
+                throw new \LogicException('Precedence adaptation must have trait');
+            }
+
+            $this->type = self::TYPE_PRECEDENCE;
+        }
+
+        if ($this->type !== self::TYPE_PRECEDENCE) {
+            throw new \LogicException('Cannot add overwritten traits for not precedence adaptation buider');
+        }
+
+        foreach ($traits as $trait) {
+            $this->insteadof[] = BuilderHelpers::normalizeName($trait);
+        }
+
+        return $this;
+    }
+
+    protected function setModifier(int $modifier): void {
+        if ($this->type === self::TYPE_UNDEFINED) {
+            $this->type = self::TYPE_ALIAS;
+        }
+
+        if ($this->type !== self::TYPE_ALIAS) {
+            throw new \LogicException('Cannot set access modifier for not alias adaptation buider');
+        }
+
+        if (is_null($this->modifier)) {
+            $this->modifier = $modifier;
+        } else {
+            throw new \LogicException('Multiple access type modifiers are not allowed');
+        }
+    }
+
+    /**
+     * Returns the built node.
+     *
+     * @return Node The built node
+     */
+    public function getNode(): Node {
+        switch ($this->type) {
+            case self::TYPE_ALIAS:
+                return new Stmt\TraitUseAdaptation\Alias($this->trait, $this->method, $this->modifier, $this->alias);
+            case self::TYPE_PRECEDENCE:
+                return new Stmt\TraitUseAdaptation\Precedence($this->trait, $this->method, $this->insteadof);
+            default:
+                throw new \LogicException('Type of adaptation is not defined');
+        }
+    }
+}

lib/PhpParser/Builder/Trait_.php

@@ -1,23 +1,31 @@
-<?php
+<?php declare(strict_types=1);
 
 namespace PhpParser\Builder;
 
 use PhpParser;
-use PhpParser\Node\Name;
+use PhpParser\BuilderHelpers;
+use PhpParser\Node;
 use PhpParser\Node\Stmt;
 
-class Trait_ extends Declaration
-{
-    protected $name;
-    protected $properties = array();
-    protected $methods = array();
+class Trait_ extends Declaration {
+    protected string $name;
+    /** @var list<Stmt\TraitUse> */
+    protected array $uses = [];
+    /** @var list<Stmt\ClassConst> */
+    protected array $constants = [];
+    /** @var list<Stmt\Property> */
+    protected array $properties = [];
+    /** @var list<Stmt\ClassMethod> */
+    protected array $methods = [];
+    /** @var list<Node\AttributeGroup> */
+    protected array $attributeGroups = [];
 
     /**
      * Creates an interface builder.
      *
      * @param string $name Name of the interface
      */
-    public function __construct($name) {
+    public function __construct(string $name) {
         $this->name = $name;
     }
 
@@ -29,12 +37,16 @@ class Trait_ extends Declaration
      * @return $this The builder instance (for fluid interface)
      */
     public function addStmt($stmt) {
-        $stmt = $this->normalizeNode($stmt);
+        $stmt = BuilderHelpers::normalizeNode($stmt);
 
         if ($stmt instanceof Stmt\Property) {
             $this->properties[] = $stmt;
-        } else if ($stmt instanceof Stmt\ClassMethod) {
+        } elseif ($stmt instanceof Stmt\ClassMethod) {
             $this->methods[] = $stmt;
+        } elseif ($stmt instanceof Stmt\TraitUse) {
+            $this->uses[] = $stmt;
+        } elseif ($stmt instanceof Stmt\ClassConst) {
+            $this->constants[] = $stmt;
         } else {
             throw new \LogicException(sprintf('Unexpected node of type "%s"', $stmt->getType()));
         }
@@ -42,14 +54,30 @@ class Trait_ extends Declaration
         return $this;
     }
 
+    /**
+     * Adds an attribute group.
+     *
+     * @param Node\Attribute|Node\AttributeGroup $attribute
+     *
+     * @return $this The builder instance (for fluid interface)
+     */
+    public function addAttribute($attribute) {
+        $this->attributeGroups[] = BuilderHelpers::normalizeAttribute($attribute);
+
+        return $this;
+    }
+
     /**
      * Returns the built trait node.
      *
      * @return Stmt\Trait_ The built interface node
      */
-    public function getNode() {
+    public function getNode(): PhpParser\Node {
         return new Stmt\Trait_(
-            $this->name, array_merge($this->properties, $this->methods), $this->attributes
+            $this->name, [
+                'stmts' => array_merge($this->uses, $this->constants, $this->properties, $this->methods),
+                'attrGroups' => $this->attributeGroups,
+            ], $this->attributes
         );
     }
 }

lib/PhpParser/Builder/Use_.php

@@ -1,27 +1,26 @@
-<?php
+<?php declare(strict_types=1);
 
 namespace PhpParser\Builder;
 
-use PhpParser\BuilderAbstract;
+use PhpParser\Builder;
+use PhpParser\BuilderHelpers;
 use PhpParser\Node;
 use PhpParser\Node\Stmt;
 
-/**
- * @method $this as(string $alias) Sets alias for used name.
- */
-class Use_ extends BuilderAbstract {
-    protected $name;
-    protected $type;
-    protected $alias = null;
+class Use_ implements Builder {
+    protected Node\Name $name;
+    /** @var Stmt\Use_::TYPE_* */
+    protected int $type;
+    protected ?string $alias = null;
 
     /**
      * Creates a name use (alias) builder.
      *
      * @param Node\Name|string $name Name of the entity (namespace, class, function, constant) to alias
-     * @param int              $type One of the Stmt\Use_::TYPE_* constants
+     * @param Stmt\Use_::TYPE_* $type One of the Stmt\Use_::TYPE_* constants
      */
-    public function __construct($name, $type) {
-        $this->name = $this->normalizeName($name);
+    public function __construct($name, int $type) {
+        $this->name = BuilderHelpers::normalizeName($name);
         $this->type = $type;
     }
 
@@ -32,27 +31,19 @@ class Use_ extends BuilderAbstract {
      *
      * @return $this The builder instance (for fluid interface)
      */
-    protected function as_($alias) {
+    public function as(string $alias) {
         $this->alias = $alias;
         return $this;
     }
-    public function __call($name, $args) {
-        if (method_exists($this, $name . '_')) {
-            return call_user_func_array(array($this, $name . '_'), $args);
-        }
-
-        throw new \LogicException(sprintf('Method "%s" does not exist', $name));
-    }
 
     /**
      * Returns the built node.
      *
-     * @return Node The built node
+     * @return Stmt\Use_ The built node
      */
-    public function getNode() {
-        $alias = null !== $this->alias ? $this->alias : $this->name->getLast();
-        return new Stmt\Use_(array(
-            new Stmt\UseUse($this->name, $alias)
-        ), $this->type);
+    public function getNode(): Node {
+        return new Stmt\Use_([
+            new Node\UseItem($this->name, $this->alias)
+        ], $this->type);
     }
 }

lib/PhpParser/BuilderAbstract.php

@@ -1,131 +0,0 @@
-<?php
-
-namespace PhpParser;
-
-use PhpParser\Node\Name;
-use PhpParser\Node\Expr;
-use PhpParser\Node\Stmt;
-use PhpParser\Node\Scalar;
-use PhpParser\Comment;
-
-abstract class BuilderAbstract implements Builder {
-    /**
-     * Normalizes a node: Converts builder objects to nodes.
-     *
-     * @param Node|Builder $node The node to normalize
-     *
-     * @return Node The normalized node
-     */
-    protected function normalizeNode($node) {
-        if ($node instanceof Builder) {
-            return $node->getNode();
-        } elseif ($node instanceof Node) {
-            return $node;
-        }
-
-        throw new \LogicException('Expected node or builder object');
-    }
-
-    /**
-     * Normalizes a name: Converts plain string names to PhpParser\Node\Name.
-     *
-     * @param Name|string $name The name to normalize
-     *
-     * @return Name The normalized name
-     */
-    protected function normalizeName($name) {
-        if ($name instanceof Name) {
-            return $name;
-        } elseif (is_string($name)) {
-            if (!$name) {
-                throw new \LogicException('Name cannot be empty');
-            }
-
-            if ($name[0] == '\\') {
-                return new Name\FullyQualified(substr($name, 1));
-            } elseif (0 === strpos($name, 'namespace\\')) {
-                return new Name\Relative(substr($name, strlen('namespace\\')));
-            } else {
-                return new Name($name);
-            }
-        }
-
-        throw new \LogicException('Name must be a string or an instance of PhpParser\Node\Name');
-    }
-
-    /**
-     * Normalizes a value: Converts nulls, booleans, integers,
-     * floats, strings and arrays into their respective nodes
-     *
-     * @param mixed $value The value to normalize
-     *
-     * @return Expr The normalized value
-     */
-    protected function normalizeValue($value) {
-        if ($value instanceof Node) {
-            return $value;
-        } elseif (is_null($value)) {
-            return new Expr\ConstFetch(
-                new Name('null')
-            );
-        } elseif (is_bool($value)) {
-            return new Expr\ConstFetch(
-                new Name($value ? 'true' : 'false')
-            );
-        } elseif (is_int($value)) {
-            return new Scalar\LNumber($value);
-        } elseif (is_float($value)) {
-            return new Scalar\DNumber($value);
-        } elseif (is_string($value)) {
-            return new Scalar\String_($value);
-        } elseif (is_array($value)) {
-            $items = array();
-            $lastKey = -1;
-            foreach ($value as $itemKey => $itemValue) {
-                // for consecutive, numeric keys don't generate keys
-                if (null !== $lastKey && ++$lastKey === $itemKey) {
-                    $items[] = new Expr\ArrayItem(
-                        $this->normalizeValue($itemValue)
-                    );
-                } else {
-                    $lastKey = null;
-                    $items[] = new Expr\ArrayItem(
-                        $this->normalizeValue($itemValue),
-                        $this->normalizeValue($itemKey)
-                    );
-                }
-            }
-
-            return new Expr\Array_($items);
-        } else {
-            throw new \LogicException('Invalid value');
-        }
-    }
-
-    /**
-     * Normalizes a doc comment: Converts plain strings to PhpParser\Comment\Doc.
-     *
-     * @param Comment\Doc|string $docComment The doc comment to normalize
-     *
-     * @return Comment\Doc The normalized doc comment
-     */
-    protected function normalizeDocComment($docComment) {
-        if ($docComment instanceof Comment\Doc) {
-            return $docComment;
-        } else if (is_string($docComment)) {
-            return new Comment\Doc($docComment);
-        } else {
-            throw new \LogicException('Doc comment must be a string or an instance of PhpParser\Comment\Doc');
-        }
-    }
-
-    /**
-     * Sets a modifier in the $this->type property.
-     *
-     * @param int $modifier Modifier to set
-     */
-    protected function setModifier($modifier) {
-        Stmt\Class_::verifyModifier($this->type, $modifier);
-        $this->type |= $modifier;
-    }
-}

lib/PhpParser/BuilderFactory.php

@@ -1,31 +1,37 @@
-<?php
+<?php declare(strict_types=1);
 
 namespace PhpParser;
 
-use PhpParser\Builder;
+use PhpParser\Node\Arg;
+use PhpParser\Node\Expr;
+use PhpParser\Node\Expr\BinaryOp\Concat;
+use PhpParser\Node\Identifier;
+use PhpParser\Node\Name;
+use PhpParser\Node\Scalar\String_;
 use PhpParser\Node\Stmt\Use_;
 
-/**
- * The following methods use reserved keywords, so their implementation is defined with an underscore and made available
- * with the reserved name through __call() magic.
- *
- * @method Builder\Namespace_ namespace(string $name) Creates a namespace builder.
- * @method Builder\Class_     class(string $name)     Creates a class builder.
- * @method Builder\Interface_ interface(string $name) Creates an interface builder.
- * @method Builder\Trait_     trait(string $name)     Creates a trait builder.
- * @method Builder\Function_  function(string $name)  Creates a function builder.
- * @method Builder\Use_       use(string $name)       Creates a namespace/class use builder.
- */
-class BuilderFactory
-{
+class BuilderFactory {
+    /**
+     * Creates an attribute node.
+     *
+     * @param string|Name $name Name of the attribute
+     * @param array $args Attribute named arguments
+     */
+    public function attribute($name, array $args = []): Node\Attribute {
+        return new Node\Attribute(
+            BuilderHelpers::normalizeName($name),
+            $this->args($args)
+        );
+    }
+
     /**
      * Creates a namespace builder.
-     * 
+     *
      * @param null|string|Node\Name $name Name of the namespace
      *
      * @return Builder\Namespace_ The created namespace builder
      */
-    protected function _namespace($name) {
+    public function namespace($name): Builder\Namespace_ {
         return new Builder\Namespace_($name);
     }
 
@@ -36,7 +42,7 @@ class BuilderFactory
      *
      * @return Builder\Class_ The created class builder
      */
-    protected function _class($name) {
+    public function class(string $name): Builder\Class_ {
         return new Builder\Class_($name);
     }
 
@@ -47,7 +53,7 @@ class BuilderFactory
      *
      * @return Builder\Interface_ The created interface builder
      */
-    protected function _interface($name) {
+    public function interface(string $name): Builder\Interface_ {
         return new Builder\Interface_($name);
     }
 
@@ -58,10 +64,49 @@ class BuilderFactory
      *
      * @return Builder\Trait_ The created trait builder
      */
-    protected function _trait($name) {
+    public function trait(string $name): Builder\Trait_ {
         return new Builder\Trait_($name);
     }
 
+    /**
+     * Creates an enum builder.
+     *
+     * @param string $name Name of the enum
+     *
+     * @return Builder\Enum_ The created enum builder
+     */
+    public function enum(string $name): Builder\Enum_ {
+        return new Builder\Enum_($name);
+    }
+
+    /**
+     * Creates a trait use builder.
+     *
+     * @param Node\Name|string ...$traits Trait names
+     *
+     * @return Builder\TraitUse The created trait use builder
+     */
+    public function useTrait(...$traits): Builder\TraitUse {
+        return new Builder\TraitUse(...$traits);
+    }
+
+    /**
+     * Creates a trait use adaptation builder.
+     *
+     * @param Node\Name|string|null $trait Trait name
+     * @param Node\Identifier|string $method Method name
+     *
+     * @return Builder\TraitUseAdaptation The created trait use adaptation builder
+     */
+    public function traitUseAdaptation($trait, $method = null): Builder\TraitUseAdaptation {
+        if ($method === null) {
+            $method = $trait;
+            $trait = null;
+        }
+
+        return new Builder\TraitUseAdaptation($trait, $method);
+    }
+
     /**
      * Creates a method builder.
      *
@@ -69,7 +114,7 @@ class BuilderFactory
      *
      * @return Builder\Method The created method builder
      */
-    public function method($name) {
+    public function method(string $name): Builder\Method {
         return new Builder\Method($name);
     }
 
@@ -80,7 +125,7 @@ class BuilderFactory
      *
      * @return Builder\Param The created parameter builder
      */
-    public function param($name) {
+    public function param(string $name): Builder\Param {
         return new Builder\Param($name);
     }
 
@@ -91,7 +136,7 @@ class BuilderFactory
      *
      * @return Builder\Property The created property builder
      */
-    public function property($name) {
+    public function property(string $name): Builder\Property {
         return new Builder\Property($name);
     }
 
@@ -102,26 +147,229 @@ class BuilderFactory
      *
      * @return Builder\Function_ The created function builder
      */
-    protected function _function($name) {
+    public function function(string $name): Builder\Function_ {
         return new Builder\Function_($name);
     }
 
     /**
      * Creates a namespace/class use builder.
      *
-     * @param string|Node\Name Name to alias
+     * @param Node\Name|string $name Name of the entity (namespace or class) to alias
      *
-     * @return Builder\Use_ The create use builder
+     * @return Builder\Use_ The created use builder
      */
-    protected function _use($name) {
+    public function use($name): Builder\Use_ {
         return new Builder\Use_($name, Use_::TYPE_NORMAL);
     }
 
-    public function __call($name, array $args) {
-        if (method_exists($this, '_' . $name)) {
-            return call_user_func_array(array($this, '_' . $name), $args);
+    /**
+     * Creates a function use builder.
+     *
+     * @param Node\Name|string $name Name of the function to alias
+     *
+     * @return Builder\Use_ The created use function builder
+     */
+    public function useFunction($name): Builder\Use_ {
+        return new Builder\Use_($name, Use_::TYPE_FUNCTION);
+    }
+
+    /**
+     * Creates a constant use builder.
+     *
+     * @param Node\Name|string $name Name of the const to alias
+     *
+     * @return Builder\Use_ The created use const builder
+     */
+    public function useConst($name): Builder\Use_ {
+        return new Builder\Use_($name, Use_::TYPE_CONSTANT);
+    }
+
+    /**
+     * Creates a class constant builder.
+     *
+     * @param string|Identifier $name Name
+     * @param Node\Expr|bool|null|int|float|string|array $value Value
+     *
+     * @return Builder\ClassConst The created use const builder
+     */
+    public function classConst($name, $value): Builder\ClassConst {
+        return new Builder\ClassConst($name, $value);
+    }
+
+    /**
+     * Creates an enum case builder.
+     *
+     * @param string|Identifier $name Name
+     *
+     * @return Builder\EnumCase The created use const builder
+     */
+    public function enumCase($name): Builder\EnumCase {
+        return new Builder\EnumCase($name);
+    }
+
+    /**
+     * Creates node a for a literal value.
+     *
+     * @param Expr|bool|null|int|float|string|array $value $value
+     */
+    public function val($value): Expr {
+        return BuilderHelpers::normalizeValue($value);
+    }
+
+    /**
+     * Creates variable node.
+     *
+     * @param string|Expr $name Name
+     */
+    public function var($name): Expr\Variable {
+        if (!\is_string($name) && !$name instanceof Expr) {
+            throw new \LogicException('Variable name must be string or Expr');
         }
 
-        throw new \LogicException(sprintf('Method "%s" does not exist', $name));
+        return new Expr\Variable($name);
+    }
+
+    /**
+     * Normalizes an argument list.
+     *
+     * Creates Arg nodes for all arguments and converts literal values to expressions.
+     *
+     * @param array $args List of arguments to normalize
+     *
+     * @return list<Arg>
+     */
+    public function args(array $args): array {
+        $normalizedArgs = [];
+        foreach ($args as $key => $arg) {
+            if (!($arg instanceof Arg)) {
+                $arg = new Arg(BuilderHelpers::normalizeValue($arg));
+            }
+            if (\is_string($key)) {
+                $arg->name = BuilderHelpers::normalizeIdentifier($key);
+            }
+            $normalizedArgs[] = $arg;
+        }
+        return $normalizedArgs;
+    }
+
+    /**
+     * Creates a function call node.
+     *
+     * @param string|Name|Expr $name Function name
+     * @param array $args Function arguments
+     */
+    public function funcCall($name, array $args = []): Expr\FuncCall {
+        return new Expr\FuncCall(
+            BuilderHelpers::normalizeNameOrExpr($name),
+            $this->args($args)
+        );
+    }
+
+    /**
+     * Creates a method call node.
+     *
+     * @param Expr $var Variable the method is called on
+     * @param string|Identifier|Expr $name Method name
+     * @param array $args Method arguments
+     */
+    public function methodCall(Expr $var, $name, array $args = []): Expr\MethodCall {
+        return new Expr\MethodCall(
+            $var,
+            BuilderHelpers::normalizeIdentifierOrExpr($name),
+            $this->args($args)
+        );
+    }
+
+    /**
+     * Creates a static method call node.
+     *
+     * @param string|Name|Expr $class Class name
+     * @param string|Identifier|Expr $name Method name
+     * @param array $args Method arguments
+     */
+    public function staticCall($class, $name, array $args = []): Expr\StaticCall {
+        return new Expr\StaticCall(
+            BuilderHelpers::normalizeNameOrExpr($class),
+            BuilderHelpers::normalizeIdentifierOrExpr($name),
+            $this->args($args)
+        );
+    }
+
+    /**
+     * Creates an object creation node.
+     *
+     * @param string|Name|Expr $class Class name
+     * @param array $args Constructor arguments
+     */
+    public function new($class, array $args = []): Expr\New_ {
+        return new Expr\New_(
+            BuilderHelpers::normalizeNameOrExpr($class),
+            $this->args($args)
+        );
+    }
+
+    /**
+     * Creates a constant fetch node.
+     *
+     * @param string|Name $name Constant name
+     */
+    public function constFetch($name): Expr\ConstFetch {
+        return new Expr\ConstFetch(BuilderHelpers::normalizeName($name));
+    }
+
+    /**
+     * Creates a property fetch node.
+     *
+     * @param Expr $var Variable holding object
+     * @param string|Identifier|Expr $name Property name
+     */
+    public function propertyFetch(Expr $var, $name): Expr\PropertyFetch {
+        return new Expr\PropertyFetch($var, BuilderHelpers::normalizeIdentifierOrExpr($name));
+    }
+
+    /**
+     * Creates a class constant fetch node.
+     *
+     * @param string|Name|Expr $class Class name
+     * @param string|Identifier|Expr $name Constant name
+     */
+    public function classConstFetch($class, $name): Expr\ClassConstFetch {
+        return new Expr\ClassConstFetch(
+            BuilderHelpers::normalizeNameOrExpr($class),
+            BuilderHelpers::normalizeIdentifierOrExpr($name)
+        );
+    }
+
+    /**
+     * Creates nested Concat nodes from a list of expressions.
+     *
+     * @param Expr|string ...$exprs Expressions or literal strings
+     */
+    public function concat(...$exprs): Concat {
+        $numExprs = count($exprs);
+        if ($numExprs < 2) {
+            throw new \LogicException('Expected at least two expressions');
+        }
+
+        $lastConcat = $this->normalizeStringExpr($exprs[0]);
+        for ($i = 1; $i < $numExprs; $i++) {
+            $lastConcat = new Concat($lastConcat, $this->normalizeStringExpr($exprs[$i]));
+        }
+        return $lastConcat;
+    }
+
+    /**
+     * @param string|Expr $expr
+     */
+    private function normalizeStringExpr($expr): Expr {
+        if ($expr instanceof Expr) {
+            return $expr;
+        }
+
+        if (\is_string($expr)) {
+            return new String_($expr);
+        }
+
+        throw new \LogicException('Expected string or Expr');
     }
 }

lib/PhpParser/BuilderHelpers.php

@@ -0,0 +1,333 @@
+<?php declare(strict_types=1);
+
+namespace PhpParser;
+
+use PhpParser\Node\ComplexType;
+use PhpParser\Node\Expr;
+use PhpParser\Node\Identifier;
+use PhpParser\Node\Name;
+use PhpParser\Node\NullableType;
+use PhpParser\Node\Scalar;
+use PhpParser\Node\Stmt;
+
+/**
+ * This class defines helpers used in the implementation of builders. Don't use it directly.
+ *
+ * @internal
+ */
+final class BuilderHelpers {
+    /**
+     * Normalizes a node: Converts builder objects to nodes.
+     *
+     * @param Node|Builder $node The node to normalize
+     *
+     * @return Node The normalized node
+     */
+    public static function normalizeNode($node): Node {
+        if ($node instanceof Builder) {
+            return $node->getNode();
+        }
+
+        if ($node instanceof Node) {
+            return $node;
+        }
+
+        throw new \LogicException('Expected node or builder object');
+    }
+
+    /**
+     * Normalizes a node to a statement.
+     *
+     * Expressions are wrapped in a Stmt\Expression node.
+     *
+     * @param Node|Builder $node The node to normalize
+     *
+     * @return Stmt The normalized statement node
+     */
+    public static function normalizeStmt($node): Stmt {
+        $node = self::normalizeNode($node);
+        if ($node instanceof Stmt) {
+            return $node;
+        }
+
+        if ($node instanceof Expr) {
+            return new Stmt\Expression($node);
+        }
+
+        throw new \LogicException('Expected statement or expression node');
+    }
+
+    /**
+     * Normalizes strings to Identifier.
+     *
+     * @param string|Identifier $name The identifier to normalize
+     *
+     * @return Identifier The normalized identifier
+     */
+    public static function normalizeIdentifier($name): Identifier {
+        if ($name instanceof Identifier) {
+            return $name;
+        }
+
+        if (\is_string($name)) {
+            return new Identifier($name);
+        }
+
+        throw new \LogicException('Expected string or instance of Node\Identifier');
+    }
+
+    /**
+     * Normalizes strings to Identifier, also allowing expressions.
+     *
+     * @param string|Identifier|Expr $name The identifier to normalize
+     *
+     * @return Identifier|Expr The normalized identifier or expression
+     */
+    public static function normalizeIdentifierOrExpr($name) {
+        if ($name instanceof Identifier || $name instanceof Expr) {
+            return $name;
+        }
+
+        if (\is_string($name)) {
+            return new Identifier($name);
+        }
+
+        throw new \LogicException('Expected string or instance of Node\Identifier or Node\Expr');
+    }
+
+    /**
+     * Normalizes a name: Converts string names to Name nodes.
+     *
+     * @param Name|string $name The name to normalize
+     *
+     * @return Name The normalized name
+     */
+    public static function normalizeName($name): Name {
+        if ($name instanceof Name) {
+            return $name;
+        }
+
+        if (is_string($name)) {
+            if (!$name) {
+                throw new \LogicException('Name cannot be empty');
+            }
+
+            if ($name[0] === '\\') {
+                return new Name\FullyQualified(substr($name, 1));
+            }
+
+            if (0 === strpos($name, 'namespace\\')) {
+                return new Name\Relative(substr($name, strlen('namespace\\')));
+            }
+
+            return new Name($name);
+        }
+
+        throw new \LogicException('Name must be a string or an instance of Node\Name');
+    }
+
+    /**
+     * Normalizes a name: Converts string names to Name nodes, while also allowing expressions.
+     *
+     * @param Expr|Name|string $name The name to normalize
+     *
+     * @return Name|Expr The normalized name or expression
+     */
+    public static function normalizeNameOrExpr($name) {
+        if ($name instanceof Expr) {
+            return $name;
+        }
+
+        if (!is_string($name) && !($name instanceof Name)) {
+            throw new \LogicException(
+                'Name must be a string or an instance of Node\Name or Node\Expr'
+            );
+        }
+
+        return self::normalizeName($name);
+    }
+
+    /**
+     * Normalizes a type: Converts plain-text type names into proper AST representation.
+     *
+     * In particular, builtin types become Identifiers, custom types become Names and nullables
+     * are wrapped in NullableType nodes.
+     *
+     * @param string|Name|Identifier|ComplexType $type The type to normalize
+     *
+     * @return Name|Identifier|ComplexType The normalized type
+     */
+    public static function normalizeType($type) {
+        if (!is_string($type)) {
+            if (
+                !$type instanceof Name && !$type instanceof Identifier &&
+                !$type instanceof ComplexType
+            ) {
+                throw new \LogicException(
+                    'Type must be a string, or an instance of Name, Identifier or ComplexType'
+                );
+            }
+            return $type;
+        }
+
+        $nullable = false;
+        if (strlen($type) > 0 && $type[0] === '?') {
+            $nullable = true;
+            $type = substr($type, 1);
+        }
+
+        $builtinTypes = [
+            'array',
+            'callable',
+            'bool',
+            'int',
+            'float',
+            'string',
+            'iterable',
+            'void',
+            'object',
+            'null',
+            'false',
+            'mixed',
+            'never',
+            'true',
+        ];
+
+        $lowerType = strtolower($type);
+        if (in_array($lowerType, $builtinTypes)) {
+            $type = new Identifier($lowerType);
+        } else {
+            $type = self::normalizeName($type);
+        }
+
+        $notNullableTypes = [
+            'void', 'mixed', 'never',
+        ];
+        if ($nullable && in_array((string) $type, $notNullableTypes)) {
+            throw new \LogicException(sprintf('%s type cannot be nullable', $type));
+        }
+
+        return $nullable ? new NullableType($type) : $type;
+    }
+
+    /**
+     * Normalizes a value: Converts nulls, booleans, integers,
+     * floats, strings and arrays into their respective nodes
+     *
+     * @param Node\Expr|bool|null|int|float|string|array $value The value to normalize
+     *
+     * @return Expr The normalized value
+     */
+    public static function normalizeValue($value): Expr {
+        if ($value instanceof Node\Expr) {
+            return $value;
+        }
+
+        if (is_null($value)) {
+            return new Expr\ConstFetch(
+                new Name('null')
+            );
+        }
+
+        if (is_bool($value)) {
+            return new Expr\ConstFetch(
+                new Name($value ? 'true' : 'false')
+            );
+        }
+
+        if (is_int($value)) {
+            return new Scalar\Int_($value);
+        }
+
+        if (is_float($value)) {
+            return new Scalar\Float_($value);
+        }
+
+        if (is_string($value)) {
+            return new Scalar\String_($value);
+        }
+
+        if (is_array($value)) {
+            $items = [];
+            $lastKey = -1;
+            foreach ($value as $itemKey => $itemValue) {
+                // for consecutive, numeric keys don't generate keys
+                if (null !== $lastKey && ++$lastKey === $itemKey) {
+                    $items[] = new Node\ArrayItem(
+                        self::normalizeValue($itemValue)
+                    );
+                } else {
+                    $lastKey = null;
+                    $items[] = new Node\ArrayItem(
+                        self::normalizeValue($itemValue),
+                        self::normalizeValue($itemKey)
+                    );
+                }
+            }
+
+            return new Expr\Array_($items);
+        }
+
+        throw new \LogicException('Invalid value');
+    }
+
+    /**
+     * Normalizes a doc comment: Converts plain strings to PhpParser\Comment\Doc.
+     *
+     * @param Comment\Doc|string $docComment The doc comment to normalize
+     *
+     * @return Comment\Doc The normalized doc comment
+     */
+    public static function normalizeDocComment($docComment): Comment\Doc {
+        if ($docComment instanceof Comment\Doc) {
+            return $docComment;
+        }
+
+        if (is_string($docComment)) {
+            return new Comment\Doc($docComment);
+        }
+
+        throw new \LogicException('Doc comment must be a string or an instance of PhpParser\Comment\Doc');
+    }
+
+    /**
+     * Normalizes a attribute: Converts attribute to the Attribute Group if needed.
+     *
+     * @param Node\Attribute|Node\AttributeGroup $attribute
+     *
+     * @return Node\AttributeGroup The Attribute Group
+     */
+    public static function normalizeAttribute($attribute): Node\AttributeGroup {
+        if ($attribute instanceof Node\AttributeGroup) {
+            return $attribute;
+        }
+
+        if (!($attribute instanceof Node\Attribute)) {
+            throw new \LogicException('Attribute must be an instance of PhpParser\Node\Attribute or PhpParser\Node\AttributeGroup');
+        }
+
+        return new Node\AttributeGroup([$attribute]);
+    }
+
+    /**
+     * Adds a modifier and returns new modifier bitmask.
+     *
+     * @param int $modifiers Existing modifiers
+     * @param int $modifier Modifier to set
+     *
+     * @return int New modifiers
+     */
+    public static function addModifier(int $modifiers, int $modifier): int {
+        Modifiers::verifyModifier($modifiers, $modifier);
+        return $modifiers | $modifier;
+    }
+
+    /**
+     * Adds a modifier and returns new modifier bitmask.
+     * @return int New modifiers
+     */
+    public static function addClassModifier(int $existingModifiers, int $modifierToSet): int {
+        Modifiers::verifyClassModifier($existingModifiers, $modifierToSet);
+        return $existingModifiers | $modifierToSet;
+    }
+}

lib/PhpParser/Comment.php

@@ -1,21 +1,36 @@
-<?php
+<?php declare(strict_types=1);
 
 namespace PhpParser;
 
-class Comment
-{
-    protected $text;
-    protected $line;
+class Comment implements \JsonSerializable {
+    protected string $text;
+    protected int $startLine;
+    protected int $startFilePos;
+    protected int $startTokenPos;
+    protected int $endLine;
+    protected int $endFilePos;
+    protected int $endTokenPos;
 
     /**
      * Constructs a comment node.
      *
      * @param string $text Comment text (including comment delimiters like /*)
-     * @param int    $line Line number the comment started on
+     * @param int $startLine Line number the comment started on
+     * @param int $startFilePos File offset the comment started on
+     * @param int $startTokenPos Token offset the comment started on
      */
-    public function __construct($text, $line = -1) {
+    public function __construct(
+        string $text,
+        int $startLine = -1, int $startFilePos = -1, int $startTokenPos = -1,
+        int $endLine = -1, int $endFilePos = -1, int $endTokenPos = -1
+    ) {
         $this->text = $text;
-        $this->line = $line;
+        $this->startLine = $startLine;
+        $this->startFilePos = $startFilePos;
+        $this->startTokenPos = $startTokenPos;
+        $this->endLine = $endLine;
+        $this->endFilePos = $endFilePos;
+        $this->endTokenPos = $endTokenPos;
     }
 
     /**
@@ -23,35 +38,62 @@ class Comment
      *
      * @return string The comment text (including comment delimiters like /*)
      */
-    public function getText() {
+    public function getText(): string {
         return $this->text;
     }
 
-    /**
-     * Sets the comment text.
-     *
-     * @param string $text The comment text (including comment delimiters like /*)
-     */
-    public function setText($text) {
-        $this->text = $text;
-    }
-
     /**
      * Gets the line number the comment started on.
      *
-     * @return int Line number
+     * @return int Line number (or -1 if not available)
      */
-    public function getLine() {
-        return $this->line;
+    public function getStartLine(): int {
+        return $this->startLine;
     }
 
     /**
-     * Sets the line number the comment started on.
+     * Gets the file offset the comment started on.
      *
-     * @param int $line Line number
+     * @return int File offset (or -1 if not available)
      */
-    public function setLine($line) {
-        $this->line = $line;
+    public function getStartFilePos(): int {
+        return $this->startFilePos;
+    }
+
+    /**
+     * Gets the token offset the comment started on.
+     *
+     * @return int Token offset (or -1 if not available)
+     */
+    public function getStartTokenPos(): int {
+        return $this->startTokenPos;
+    }
+
+    /**
+     * Gets the line number the comment ends on.
+     *
+     * @return int Line number (or -1 if not available)
+     */
+    public function getEndLine(): int {
+        return $this->endLine;
+    }
+
+    /**
+     * Gets the file offset the comment ends on.
+     *
+     * @return int File offset (or -1 if not available)
+     */
+    public function getEndFilePos(): int {
+        return $this->endFilePos;
+    }
+
+    /**
+     * Gets the token offset the comment ends on.
+     *
+     * @return int Token offset (or -1 if not available)
+     */
+    public function getEndTokenPos(): int {
+        return $this->endTokenPos;
     }
 
     /**
@@ -59,7 +101,7 @@ class Comment
      *
      * @return string The comment text (including comment delimiters like /*)
      */
-    public function __toString() {
+    public function __toString(): string {
         return $this->text;
     }
 
@@ -68,17 +110,19 @@ class Comment
      *
      * "Reformatted" here means that we try to clean up the whitespace at the
      * starts of the lines. This is necessary because we receive the comments
-     * without trailing whitespace on the first line, but with trailing whitespace
+     * without leading whitespace on the first line, but with leading whitespace
      * on all subsequent lines.
      *
-     * @return mixed|string
+     * Additionally, this normalizes CRLF newlines to LF newlines.
      */
-    public function getReformattedText() {
-        $text = trim($this->text);
-        if (false === strpos($text, "\n")) {
+    public function getReformattedText(): string {
+        $text = str_replace("\r\n", "\n", $this->text);
+        $newlinePos = strpos($text, "\n");
+        if (false === $newlinePos) {
             // Single line comments don't need further processing
             return $text;
-        } elseif (preg_match('((*BSR_ANYCRLF)(*ANYCRLF)^.*(?:\R\s+\*.*)+$)', $text)) {
+        }
+        if (preg_match('(^.*(?:\n\s+\*.*)+$)', $text)) {
             // Multi line comment of the type
             //
             //     /*
@@ -87,8 +131,9 @@ class Comment
             //      */
             //
             // is handled by replacing the whitespace sequences before the * by a single space
-            return preg_replace('(^\s+\*)m', ' *', $this->text);
-        } elseif (preg_match('(^/\*\*?\s*[\r\n])', $text) && preg_match('(\n(\s*)\*/$)', $text, $matches)) {
+            return preg_replace('(^\s+\*)m', ' *', $text);
+        }
+        if (preg_match('(^/\*\*?\s*\n)', $text) && preg_match('(\n(\s*)\*/$)', $text, $matches)) {
             // Multi line comment of the type
             //
             //    /*
@@ -100,20 +145,63 @@ class Comment
             // */ on all lines. So if the last line is "    */", then "    " is removed at the
             // start of all lines.
             return preg_replace('(^' . preg_quote($matches[1]) . ')m', '', $text);
-        } elseif (preg_match('(^/\*\*?\s*(?!\s))', $text, $matches)) {
+        }
+        if (preg_match('(^/\*\*?\s*(?!\s))', $text, $matches)) {
             // Multi line comment of the type
             //
             //     /* Some text.
             //        Some more text.
+            //          Indented text.
             //        Even more text. */
             //
-            // is handled by taking the length of the "/* " segment and leaving only that
-            // many space characters before the lines. Thus in the above example only three
-            // space characters are left at the start of every line.
-            return preg_replace('(^\s*(?= {' . strlen($matches[0]) . '}(?!\s)))m', '', $text);
+            // is handled by removing the difference between the shortest whitespace prefix on all
+            // lines and the length of the "/* " opening sequence.
+            $prefixLen = $this->getShortestWhitespacePrefixLen(substr($text, $newlinePos + 1));
+            $removeLen = $prefixLen - strlen($matches[0]);
+            return preg_replace('(^\s{' . $removeLen . '})m', '', $text);
         }
 
         // No idea how to format this comment, so simply return as is
         return $text;
     }
-}
+
+    /**
+     * Get length of shortest whitespace prefix (at the start of a line).
+     *
+     * If there is a line with no prefix whitespace, 0 is a valid return value.
+     *
+     * @param string $str String to check
+     * @return int Length in characters. Tabs count as single characters.
+     */
+    private function getShortestWhitespacePrefixLen(string $str): int {
+        $lines = explode("\n", $str);
+        $shortestPrefixLen = \PHP_INT_MAX;
+        foreach ($lines as $line) {
+            preg_match('(^\s*)', $line, $matches);
+            $prefixLen = strlen($matches[0]);
+            if ($prefixLen < $shortestPrefixLen) {
+                $shortestPrefixLen = $prefixLen;
+            }
+        }
+        return $shortestPrefixLen;
+    }
+
+    /**
+     * @return array{nodeType:string, text:mixed, line:mixed, filePos:mixed}
+     */
+    public function jsonSerialize(): array {
+        // Technically not a node, but we make it look like one anyway
+        $type = $this instanceof Comment\Doc ? 'Comment_Doc' : 'Comment';
+        return [
+            'nodeType' => $type,
+            'text' => $this->text,
+            // TODO: Rename these to include "start".
+            'line' => $this->startLine,
+            'filePos' => $this->startFilePos,
+            'tokenPos' => $this->startTokenPos,
+            'endLine' => $this->endLine,
+            'endFilePos' => $this->endFilePos,
+            'endTokenPos' => $this->endTokenPos,
+        ];
+    }
+}

lib/PhpParser/Comment/Doc.php

@@ -1,7 +1,6 @@
-<?php
+<?php declare(strict_types=1);
 
 namespace PhpParser\Comment;
 
-class Doc extends \PhpParser\Comment
-{
-}
+class Doc extends \PhpParser\Comment {
+}

lib/PhpParser/ConstExprEvaluationException.php

@@ -0,0 +1,6 @@
+<?php declare(strict_types=1);
+
+namespace PhpParser;
+
+class ConstExprEvaluationException extends \Exception {
+}

lib/PhpParser/ConstExprEvaluator.php

@@ -0,0 +1,234 @@
+<?php declare(strict_types=1);
+
+namespace PhpParser;
+
+use PhpParser\Node\Expr;
+use PhpParser\Node\Scalar;
+
+use function array_merge;
+
+/**
+ * Evaluates constant expressions.
+ *
+ * This evaluator is able to evaluate all constant expressions (as defined by PHP), which can be
+ * evaluated without further context. If a subexpression is not of this type, a user-provided
+ * fallback evaluator is invoked. To support all constant expressions that are also supported by
+ * PHP (and not already handled by this class), the fallback evaluator must be able to handle the
+ * following node types:
+ *
+ *  * All Scalar\MagicConst\* nodes.
+ *  * Expr\ConstFetch nodes. Only null/false/true are already handled by this class.
+ *  * Expr\ClassConstFetch nodes.
+ *
+ * The fallback evaluator should throw ConstExprEvaluationException for nodes it cannot evaluate.
+ *
+ * The evaluation is dependent on runtime configuration in two respects: Firstly, floating
+ * point to string conversions are affected by the precision ini setting. Secondly, they are also
+ * affected by the LC_NUMERIC locale.
+ */
+class ConstExprEvaluator {
+    /** @var callable|null */
+    private $fallbackEvaluator;
+
+    /**
+     * Create a constant expression evaluator.
+     *
+     * The provided fallback evaluator is invoked whenever a subexpression cannot be evaluated. See
+     * class doc comment for more information.
+     *
+     * @param callable|null $fallbackEvaluator To call if subexpression cannot be evaluated
+     */
+    public function __construct(?callable $fallbackEvaluator = null) {
+        $this->fallbackEvaluator = $fallbackEvaluator ?? function (Expr $expr) {
+            throw new ConstExprEvaluationException(
+                "Expression of type {$expr->getType()} cannot be evaluated"
+            );
+        };
+    }
+
+    /**
+     * Silently evaluates a constant expression into a PHP value.
+     *
+     * Thrown Errors, warnings or notices will be converted into a ConstExprEvaluationException.
+     * The original source of the exception is available through getPrevious().
+     *
+     * If some part of the expression cannot be evaluated, the fallback evaluator passed to the
+     * constructor will be invoked. By default, if no fallback is provided, an exception of type
+     * ConstExprEvaluationException is thrown.
+     *
+     * See class doc comment for caveats and limitations.
+     *
+     * @param Expr $expr Constant expression to evaluate
+     * @return mixed Result of evaluation
+     *
+     * @throws ConstExprEvaluationException if the expression cannot be evaluated or an error occurred
+     */
+    public function evaluateSilently(Expr $expr) {
+        set_error_handler(function ($num, $str, $file, $line) {
+            throw new \ErrorException($str, 0, $num, $file, $line);
+        });
+
+        try {
+            return $this->evaluate($expr);
+        } catch (\Throwable $e) {
+            if (!$e instanceof ConstExprEvaluationException) {
+                $e = new ConstExprEvaluationException(
+                    "An error occurred during constant expression evaluation", 0, $e);
+            }
+            throw $e;
+        } finally {
+            restore_error_handler();
+        }
+    }
+
+    /**
+     * Directly evaluates a constant expression into a PHP value.
+     *
+     * May generate Error exceptions, warnings or notices. Use evaluateSilently() to convert these
+     * into a ConstExprEvaluationException.
+     *
+     * If some part of the expression cannot be evaluated, the fallback evaluator passed to the
+     * constructor will be invoked. By default, if no fallback is provided, an exception of type
+     * ConstExprEvaluationException is thrown.
+     *
+     * See class doc comment for caveats and limitations.
+     *
+     * @param Expr $expr Constant expression to evaluate
+     * @return mixed Result of evaluation
+     *
+     * @throws ConstExprEvaluationException if the expression cannot be evaluated
+     */
+    public function evaluateDirectly(Expr $expr) {
+        return $this->evaluate($expr);
+    }
+
+    /** @return mixed */
+    private function evaluate(Expr $expr) {
+        if ($expr instanceof Scalar\Int_
+            || $expr instanceof Scalar\Float_
+            || $expr instanceof Scalar\String_
+        ) {
+            return $expr->value;
+        }
+
+        if ($expr instanceof Expr\Array_) {
+            return $this->evaluateArray($expr);
+        }
+
+        // Unary operators
+        if ($expr instanceof Expr\UnaryPlus) {
+            return +$this->evaluate($expr->expr);
+        }
+        if ($expr instanceof Expr\UnaryMinus) {
+            return -$this->evaluate($expr->expr);
+        }
+        if ($expr instanceof Expr\BooleanNot) {
+            return !$this->evaluate($expr->expr);
+        }
+        if ($expr instanceof Expr\BitwiseNot) {
+            return ~$this->evaluate($expr->expr);
+        }
+
+        if ($expr instanceof Expr\BinaryOp) {
+            return $this->evaluateBinaryOp($expr);
+        }
+
+        if ($expr instanceof Expr\Ternary) {
+            return $this->evaluateTernary($expr);
+        }
+
+        if ($expr instanceof Expr\ArrayDimFetch && null !== $expr->dim) {
+            return $this->evaluate($expr->var)[$this->evaluate($expr->dim)];
+        }
+
+        if ($expr instanceof Expr\ConstFetch) {
+            return $this->evaluateConstFetch($expr);
+        }
+
+        return ($this->fallbackEvaluator)($expr);
+    }
+
+    private function evaluateArray(Expr\Array_ $expr): array {
+        $array = [];
+        foreach ($expr->items as $item) {
+            if (null !== $item->key) {
+                $array[$this->evaluate($item->key)] = $this->evaluate($item->value);
+            } elseif ($item->unpack) {
+                $array = array_merge($array, $this->evaluate($item->value));
+            } else {
+                $array[] = $this->evaluate($item->value);
+            }
+        }
+        return $array;
+    }
+
+    /** @return mixed */
+    private function evaluateTernary(Expr\Ternary $expr) {
+        if (null === $expr->if) {
+            return $this->evaluate($expr->cond) ?: $this->evaluate($expr->else);
+        }
+
+        return $this->evaluate($expr->cond)
+            ? $this->evaluate($expr->if)
+            : $this->evaluate($expr->else);
+    }
+
+    /** @return mixed */
+    private function evaluateBinaryOp(Expr\BinaryOp $expr) {
+        if ($expr instanceof Expr\BinaryOp\Coalesce
+            && $expr->left instanceof Expr\ArrayDimFetch
+        ) {
+            // This needs to be special cased to respect BP_VAR_IS fetch semantics
+            return $this->evaluate($expr->left->var)[$this->evaluate($expr->left->dim)]
+                ?? $this->evaluate($expr->right);
+        }
+
+        // The evaluate() calls are repeated in each branch, because some of the operators are
+        // short-circuiting and evaluating the RHS in advance may be illegal in that case
+        $l = $expr->left;
+        $r = $expr->right;
+        switch ($expr->getOperatorSigil()) {
+            case '&':   return $this->evaluate($l) &   $this->evaluate($r);
+            case '|':   return $this->evaluate($l) |   $this->evaluate($r);
+            case '^':   return $this->evaluate($l) ^   $this->evaluate($r);
+            case '&&':  return $this->evaluate($l) &&  $this->evaluate($r);
+            case '||':  return $this->evaluate($l) ||  $this->evaluate($r);
+            case '??':  return $this->evaluate($l) ??  $this->evaluate($r);
+            case '.':   return $this->evaluate($l) .   $this->evaluate($r);
+            case '/':   return $this->evaluate($l) /   $this->evaluate($r);
+            case '==':  return $this->evaluate($l) ==  $this->evaluate($r);
+            case '>':   return $this->evaluate($l) >   $this->evaluate($r);
+            case '>=':  return $this->evaluate($l) >=  $this->evaluate($r);
+            case '===': return $this->evaluate($l) === $this->evaluate($r);
+            case 'and': return $this->evaluate($l) and $this->evaluate($r);
+            case 'or':  return $this->evaluate($l) or  $this->evaluate($r);
+            case 'xor': return $this->evaluate($l) xor $this->evaluate($r);
+            case '-':   return $this->evaluate($l) -   $this->evaluate($r);
+            case '%':   return $this->evaluate($l) %   $this->evaluate($r);
+            case '*':   return $this->evaluate($l) *   $this->evaluate($r);
+            case '!=':  return $this->evaluate($l) !=  $this->evaluate($r);
+            case '!==': return $this->evaluate($l) !== $this->evaluate($r);
+            case '+':   return $this->evaluate($l) +   $this->evaluate($r);
+            case '**':  return $this->evaluate($l) **  $this->evaluate($r);
+            case '<<':  return $this->evaluate($l) <<  $this->evaluate($r);
+            case '>>':  return $this->evaluate($l) >>  $this->evaluate($r);
+            case '<':   return $this->evaluate($l) <   $this->evaluate($r);
+            case '<=':  return $this->evaluate($l) <=  $this->evaluate($r);
+            case '<=>': return $this->evaluate($l) <=> $this->evaluate($r);
+        }
+
+        throw new \Exception('Should not happen');
+    }
+
+    /** @return mixed */
+    private function evaluateConstFetch(Expr\ConstFetch $expr) {
+        $name = $expr->name->toLowerString();
+        switch ($name) {
+            case 'null': return null;
+            case 'false': return false;
+            case 'true': return true;
+        }
+
+        return ($this->fallbackEvaluator)($expr);
+    }
+}

lib/PhpParser/Error.php

@@ -1,26 +1,21 @@
-<?php
+<?php declare(strict_types=1);
 
 namespace PhpParser;
 
-class Error extends \RuntimeException
-{
-    protected $rawMessage;
-    protected $attributes;
+class Error extends \RuntimeException {
+    protected string $rawMessage;
+    /** @var array<string, mixed> */
+    protected array $attributes;
 
     /**
      * Creates an Exception signifying a parse error.
      *
-     * @param string    $message    Error message
-     * @param array|int $attributes Attributes of node/token where error occurred
-     *                              (or start line of error -- deprecated)
+     * @param string $message Error message
+     * @param array<string, mixed> $attributes Attributes of node/token where error occurred
      */
-    public function __construct($message, $attributes = array()) {
-        $this->rawMessage = (string) $message;
-        if (is_array($attributes)) {
-            $this->attributes = $attributes;
-        } else {
-            $this->attributes = array('startLine' => $attributes);
-        }
+    public function __construct(string $message, array $attributes = []) {
+        $this->rawMessage = $message;
+        $this->attributes = $attributes;
         $this->updateMessage();
     }
 
@@ -29,7 +24,7 @@ class Error extends \RuntimeException
      *
      * @return string Error message
      */
-    public function getRawMessage() {
+    public function getRawMessage(): string {
         return $this->rawMessage;
     }
 
@@ -38,8 +33,8 @@ class Error extends \RuntimeException
      *
      * @return int Error start line
      */
-    public function getStartLine() {
-        return isset($this->attributes['startLine']) ? $this->attributes['startLine'] : -1;
+    public function getStartLine(): int {
+        return $this->attributes['startLine'] ?? -1;
     }
 
     /**
@@ -47,27 +42,36 @@ class Error extends \RuntimeException
      *
      * @return int Error end line
      */
-    public function getEndLine() {
-        return isset($this->attributes['endLine']) ? $this->attributes['endLine'] : -1;
+    public function getEndLine(): int {
+        return $this->attributes['endLine'] ?? -1;
     }
 
-
     /**
      * Gets the attributes of the node/token the error occurred at.
      *
-     * @return array
+     * @return array<string, mixed>
      */
-    public function getAttributes() {
+    public function getAttributes(): array {
         return $this->attributes;
     }
 
+    /**
+     * Sets the attributes of the node/token the error occurred at.
+     *
+     * @param array<string, mixed> $attributes
+     */
+    public function setAttributes(array $attributes): void {
+        $this->attributes = $attributes;
+        $this->updateMessage();
+    }
+
     /**
      * Sets the line of the PHP file the error occurred in.
      *
      * @param string $message Error message
      */
-    public function setRawMessage($message) {
-        $this->rawMessage = (string) $message;
+    public function setRawMessage(string $message): void {
+        $this->rawMessage = $message;
         $this->updateMessage();
     }
 
@@ -76,8 +80,8 @@ class Error extends \RuntimeException
      *
      * @param int $line Error start line
      */
-    public function setStartLine($line) {
-        $this->attributes['startLine'] = (int) $line;
+    public function setStartLine(int $line): void {
+        $this->attributes['startLine'] = $line;
         $this->updateMessage();
     }
 
@@ -85,20 +89,17 @@ class Error extends \RuntimeException
      * Returns whether the error has start and end column information.
      *
      * For column information enable the startFilePos and endFilePos in the lexer options.
-     *
-     * @return bool
      */
-    public function hasColumnInfo() {
-        return isset($this->attributes['startFilePos']) && isset($this->attributes['endFilePos']);
+    public function hasColumnInfo(): bool {
+        return isset($this->attributes['startFilePos'], $this->attributes['endFilePos']);
     }
 
     /**
      * Gets the start column (1-based) into the line where the error started.
      *
      * @param string $code Source code of the file
-     * @return int
      */
-    public function getStartColumn($code) {
+    public function getStartColumn(string $code): int {
         if (!$this->hasColumnInfo()) {
             throw new \RuntimeException('Error does not have column information');
         }
@@ -110,9 +111,8 @@ class Error extends \RuntimeException
      * Gets the end column (1-based) into the line where the error ended.
      *
      * @param string $code Source code of the file
-     * @return int
      */
-    public function getEndColumn($code) {
+    public function getEndColumn(string $code): int {
         if (!$this->hasColumnInfo()) {
             throw new \RuntimeException('Error does not have column information');
         }
@@ -120,7 +120,30 @@ class Error extends \RuntimeException
         return $this->toColumn($code, $this->attributes['endFilePos']);
     }
 
-    private function toColumn($code, $pos) {
+    /**
+     * Formats message including line and column information.
+     *
+     * @param string $code Source code associated with the error, for calculation of the columns
+     *
+     * @return string Formatted message
+     */
+    public function getMessageWithColumnInfo(string $code): string {
+        return sprintf(
+            '%s from %d:%d to %d:%d', $this->getRawMessage(),
+            $this->getStartLine(), $this->getStartColumn($code),
+            $this->getEndLine(), $this->getEndColumn($code)
+        );
+    }
+
+    /**
+     * Converts a file offset into a column.
+     *
+     * @param string $code Source code that $pos indexes into
+     * @param int $pos 0-based position in $code
+     *
+     * @return int 1-based column (relative to start of line)
+     */
+    private function toColumn(string $code, int $pos): int {
         if ($pos > strlen($code)) {
             throw new \RuntimeException('Invalid position information');
         }
@@ -136,7 +159,7 @@ class Error extends \RuntimeException
     /**
      * Updates the exception message after a change to rawMessage or rawLine.
      */
-    protected function updateMessage() {
+    protected function updateMessage(): void {
         $this->message = $this->rawMessage;
 
         if (-1 === $this->getStartLine()) {
@@ -145,14 +168,4 @@ class Error extends \RuntimeException
             $this->message .= ' on line ' . $this->getStartLine();
         }
     }
-
-    /** @deprecated Use getStartLine() instead */
-    public function getRawLine() {
-        return $this->getStartLine();
-    }
-
-    /** @deprecated Use setStartLine() instead */
-    public function setRawLine($line) {
-        $this->setStartLine($line);
-    }
 }

lib/PhpParser/ErrorHandler.php

@@ -0,0 +1,12 @@
+<?php declare(strict_types=1);
+
+namespace PhpParser;
+
+interface ErrorHandler {
+    /**
+     * Handle an error generated during lexing, parsing or some other operation.
+     *
+     * @param Error $error The error that needs to be handled
+     */
+    public function handleError(Error $error): void;
+}

lib/PhpParser/ErrorHandler/Collecting.php

@@ -0,0 +1,43 @@
+<?php declare(strict_types=1);
+
+namespace PhpParser\ErrorHandler;
+
+use PhpParser\Error;
+use PhpParser\ErrorHandler;
+
+/**
+ * Error handler that collects all errors into an array.
+ *
+ * This allows graceful handling of errors.
+ */
+class Collecting implements ErrorHandler {
+    /** @var Error[] Collected errors */
+    private array $errors = [];
+
+    public function handleError(Error $error): void {
+        $this->errors[] = $error;
+    }
+
+    /**
+     * Get collected errors.
+     *
+     * @return Error[]
+     */
+    public function getErrors(): array {
+        return $this->errors;
+    }
+
+    /**
+     * Check whether there are any errors.
+     */
+    public function hasErrors(): bool {
+        return !empty($this->errors);
+    }
+
+    /**
+     * Reset/clear collected errors.
+     */
+    public function clearErrors(): void {
+        $this->errors = [];
+    }
+}

lib/PhpParser/ErrorHandler/Throwing.php

@@ -0,0 +1,17 @@
+<?php declare(strict_types=1);
+
+namespace PhpParser\ErrorHandler;
+
+use PhpParser\Error;
+use PhpParser\ErrorHandler;
+
+/**
+ * Error handler that handles all errors by throwing them.
+ *
+ * This is the default strategy used by all components.
+ */
+class Throwing implements ErrorHandler {
+    public function handleError(Error $error): void {
+        throw $error;
+    }
+}

lib/PhpParser/Internal/DiffElem.php

@@ -0,0 +1,31 @@
+<?php declare(strict_types=1);
+
+namespace PhpParser\Internal;
+
+/**
+ * @internal
+ */
+class DiffElem {
+    public const TYPE_KEEP = 0;
+    public const TYPE_REMOVE = 1;
+    public const TYPE_ADD = 2;
+    public const TYPE_REPLACE = 3;
+
+    /** @var int One of the TYPE_* constants */
+    public int $type;
+    /** @var mixed Is null for add operations */
+    public $old;
+    /** @var mixed Is null for remove operations */
+    public $new;
+
+    /**
+     * @param int $type One of the TYPE_* constants
+     * @param mixed $old Is null for add operations
+     * @param mixed $new Is null for remove operations
+     */
+    public function __construct(int $type, $old, $new) {
+        $this->type = $type;
+        $this->old = $old;
+        $this->new = $new;
+    }
+}

lib/PhpParser/Internal/Differ.php

@@ -0,0 +1,178 @@
+<?php declare(strict_types=1);
+
+namespace PhpParser\Internal;
+
+/**
+ * Implements the Myers diff algorithm.
+ *
+ * Myers, Eugene W. "An O (ND) difference algorithm and its variations."
+ * Algorithmica 1.1 (1986): 251-266.
+ *
+ * @template T
+ * @internal
+ */
+class Differ {
+    /** @var callable(T, T): bool */
+    private $isEqual;
+
+    /**
+     * Create differ over the given equality relation.
+     *
+     * @param callable(T, T): bool $isEqual Equality relation
+     */
+    public function __construct(callable $isEqual) {
+        $this->isEqual = $isEqual;
+    }
+
+    /**
+     * Calculate diff (edit script) from $old to $new.
+     *
+     * @param T[] $old Original array
+     * @param T[] $new New array
+     *
+     * @return DiffElem[] Diff (edit script)
+     */
+    public function diff(array $old, array $new): array {
+        $old = \array_values($old);
+        $new = \array_values($new);
+        list($trace, $x, $y) = $this->calculateTrace($old, $new);
+        return $this->extractDiff($trace, $x, $y, $old, $new);
+    }
+
+    /**
+     * Calculate diff, including "replace" operations.
+     *
+     * If a sequence of remove operations is followed by the same number of add operations, these
+     * will be coalesced into replace operations.
+     *
+     * @param T[] $old Original array
+     * @param T[] $new New array
+     *
+     * @return DiffElem[] Diff (edit script), including replace operations
+     */
+    public function diffWithReplacements(array $old, array $new): array {
+        return $this->coalesceReplacements($this->diff($old, $new));
+    }
+
+    /**
+     * @param T[] $old
+     * @param T[] $new
+     * @return array{array<int, array<int, int>>, int, int}
+     */
+    private function calculateTrace(array $old, array $new): array {
+        $n = \count($old);
+        $m = \count($new);
+        $max = $n + $m;
+        $v = [1 => 0];
+        $trace = [];
+        for ($d = 0; $d <= $max; $d++) {
+            $trace[] = $v;
+            for ($k = -$d; $k <= $d; $k += 2) {
+                if ($k === -$d || ($k !== $d && $v[$k - 1] < $v[$k + 1])) {
+                    $x = $v[$k + 1];
+                } else {
+                    $x = $v[$k - 1] + 1;
+                }
+
+                $y = $x - $k;
+                while ($x < $n && $y < $m && ($this->isEqual)($old[$x], $new[$y])) {
+                    $x++;
+                    $y++;
+                }
+
+                $v[$k] = $x;
+                if ($x >= $n && $y >= $m) {
+                    return [$trace, $x, $y];
+                }
+            }
+        }
+        throw new \Exception('Should not happen');
+    }
+
+    /**
+     * @param array<int, array<int, int>> $trace
+     * @param T[] $old
+     * @param T[] $new
+     * @return DiffElem[]
+     */
+    private function extractDiff(array $trace, int $x, int $y, array $old, array $new): array {
+        $result = [];
+        for ($d = \count($trace) - 1; $d >= 0; $d--) {
+            $v = $trace[$d];
+            $k = $x - $y;
+
+            if ($k === -$d || ($k !== $d && $v[$k - 1] < $v[$k + 1])) {
+                $prevK = $k + 1;
+            } else {
+                $prevK = $k - 1;
+            }
+
+            $prevX = $v[$prevK];
+            $prevY = $prevX - $prevK;
+
+            while ($x > $prevX && $y > $prevY) {
+                $result[] = new DiffElem(DiffElem::TYPE_KEEP, $old[$x - 1], $new[$y - 1]);
+                $x--;
+                $y--;
+            }
+
+            if ($d === 0) {
+                break;
+            }
+
+            while ($x > $prevX) {
+                $result[] = new DiffElem(DiffElem::TYPE_REMOVE, $old[$x - 1], null);
+                $x--;
+            }
+
+            while ($y > $prevY) {
+                $result[] = new DiffElem(DiffElem::TYPE_ADD, null, $new[$y - 1]);
+                $y--;
+            }
+        }
+        return array_reverse($result);
+    }
+
+    /**
+     * Coalesce equal-length sequences of remove+add into a replace operation.
+     *
+     * @param DiffElem[] $diff
+     * @return DiffElem[]
+     */
+    private function coalesceReplacements(array $diff): array {
+        $newDiff = [];
+        $c = \count($diff);
+        for ($i = 0; $i < $c; $i++) {
+            $diffType = $diff[$i]->type;
+            if ($diffType !== DiffElem::TYPE_REMOVE) {
+                $newDiff[] = $diff[$i];
+                continue;
+            }
+
+            $j = $i;
+            while ($j < $c && $diff[$j]->type === DiffElem::TYPE_REMOVE) {
+                $j++;
+            }
+
+            $k = $j;
+            while ($k < $c && $diff[$k]->type === DiffElem::TYPE_ADD) {
+                $k++;
+            }
+
+            if ($j - $i === $k - $j) {
+                $len = $j - $i;
+                for ($n = 0; $n < $len; $n++) {
+                    $newDiff[] = new DiffElem(
+                        DiffElem::TYPE_REPLACE, $diff[$i + $n]->old, $diff[$j + $n]->new
+                    );
+                }
+            } else {
+                for (; $i < $k; $i++) {
+                    $newDiff[] = $diff[$i];
+                }
+            }
+            $i = $k - 1;
+        }
+        return $newDiff;
+    }
+}

lib/PhpParser/Internal/PrintableNewAnonClassNode.php

@@ -0,0 +1,71 @@
+<?php declare(strict_types=1);
+
+namespace PhpParser\Internal;
+
+use PhpParser\Node;
+use PhpParser\Node\Expr;
+
+/**
+ * This node is used internally by the format-preserving pretty printer to print anonymous classes.
+ *
+ * The normal anonymous class structure violates assumptions about the order of token offsets.
+ * Namely, the constructor arguments are part of the Expr\New_ node and follow the class node, even
+ * though they are actually interleaved with them. This special node type is used temporarily to
+ * restore a sane token offset order.
+ *
+ * @internal
+ */
+class PrintableNewAnonClassNode extends Expr {
+    /** @var Node\AttributeGroup[] PHP attribute groups */
+    public array $attrGroups;
+    /** @var int Modifiers */
+    public int $flags;
+    /** @var (Node\Arg|Node\VariadicPlaceholder)[] Arguments */
+    public array $args;
+    /** @var null|Node\Name Name of extended class */
+    public ?Node\Name $extends;
+    /** @var Node\Name[] Names of implemented interfaces */
+    public array $implements;
+    /** @var Node\Stmt[] Statements */
+    public array $stmts;
+
+    /**
+     * @param Node\AttributeGroup[] $attrGroups PHP attribute groups
+     * @param (Node\Arg|Node\VariadicPlaceholder)[] $args Arguments
+     * @param Node\Name|null $extends Name of extended class
+     * @param Node\Name[] $implements Names of implemented interfaces
+     * @param Node\Stmt[] $stmts Statements
+     * @param array<string, mixed> $attributes Attributes
+     */
+    public function __construct(
+        array $attrGroups, int $flags, array $args, ?Node\Name $extends, array $implements,
+        array $stmts, array $attributes
+    ) {
+        parent::__construct($attributes);
+        $this->attrGroups = $attrGroups;
+        $this->flags = $flags;
+        $this->args = $args;
+        $this->extends = $extends;
+        $this->implements = $implements;
+        $this->stmts = $stmts;
+    }
+
+    public static function fromNewNode(Expr\New_ $newNode): self {
+        $class = $newNode->class;
+        assert($class instanceof Node\Stmt\Class_);
+        // We don't assert that $class->name is null here, to allow consumers to assign unique names
+        // to anonymous classes for their own purposes. We simplify ignore the name here.
+        return new self(
+            $class->attrGroups, $class->flags, $newNode->args, $class->extends, $class->implements,
+            $class->stmts, $newNode->getAttributes()
+        );
+    }
+
+    public function getType(): string {
+        return 'Expr_PrintableNewAnonClass';
+    }
+
+    public function getSubNodeNames(): array {
+        return ['attrGroups', 'flags', 'args', 'extends', 'implements', 'stmts'];
+    }
+}

lib/PhpParser/Internal/TokenPolyfill.php

@@ -0,0 +1,237 @@
+<?php declare(strict_types=1);
+
+namespace PhpParser\Internal;
+
+if (\PHP_VERSION_ID >= 80000) {
+    class TokenPolyfill extends \PhpToken {
+    }
+    return;
+}
+
+/**
+ * This is a polyfill for the PhpToken class introduced in PHP 8.0. We do not actually polyfill
+ * PhpToken, because composer might end up picking a different polyfill implementation, which does
+ * not meet our requirements.
+ *
+ * @internal
+ */
+class TokenPolyfill {
+    /** @var int The ID of the token. Either a T_* constant of a character code < 256. */
+    public int $id;
+    /** @var string The textual content of the token. */
+    public string $text;
+    /** @var int The 1-based starting line of the token (or -1 if unknown). */
+    public int $line;
+    /** @var int The 0-based starting position of the token (or -1 if unknown). */
+    public int $pos;
+
+    /** @var array<int, bool> Tokens ignored by the PHP parser. */
+    private const IGNORABLE_TOKENS = [
+        \T_WHITESPACE => true,
+        \T_COMMENT => true,
+        \T_DOC_COMMENT => true,
+        \T_OPEN_TAG => true,
+    ];
+
+    /** @var array<int, bool> Tokens that may be part of a T_NAME_* identifier. */
+    private static array $identifierTokens;
+
+    /**
+     * Create a Token with the given ID and text, as well optional line and position information.
+     */
+    final public function __construct(int $id, string $text, int $line = -1, int $pos = -1) {
+        $this->id = $id;
+        $this->text = $text;
+        $this->line = $line;
+        $this->pos = $pos;
+    }
+
+    /**
+     * Get the name of the token. For single-char tokens this will be the token character.
+     * Otherwise it will be a T_* style name, or null if the token ID is unknown.
+     */
+    public function getTokenName(): ?string {
+        if ($this->id < 256) {
+            return \chr($this->id);
+        }
+
+        $name = token_name($this->id);
+        return $name === 'UNKNOWN' ? null : $name;
+    }
+
+    /**
+     * Check whether the token is of the given kind. The kind may be either an integer that matches
+     * the token ID, a string that matches the token text, or an array of integers/strings. In the
+     * latter case, the function returns true if any of the kinds in the array match.
+     *
+     * @param int|string|(int|string)[] $kind
+     */
+    public function is($kind): bool {
+        if (\is_int($kind)) {
+            return $this->id === $kind;
+        }
+        if (\is_string($kind)) {
+            return $this->text === $kind;
+        }
+        if (\is_array($kind)) {
+            foreach ($kind as $entry) {
+                if (\is_int($entry)) {
+                    if ($this->id === $entry) {
+                        return true;
+                    }
+                } elseif (\is_string($entry)) {
+                    if ($this->text === $entry) {
+                        return true;
+                    }
+                } else {
+                    throw new \TypeError(
+                        'Argument #1 ($kind) must only have elements of type string|int, ' .
+                        gettype($entry) . ' given');
+                }
+            }
+            return false;
+        }
+        throw new \TypeError(
+            'Argument #1 ($kind) must be of type string|int|array, ' .gettype($kind) . ' given');
+    }
+
+    /**
+     * Check whether this token would be ignored by the PHP parser. Returns true for T_WHITESPACE,
+     * T_COMMENT, T_DOC_COMMENT and T_OPEN_TAG, and false for everything else.
+     */
+    public function isIgnorable(): bool {
+        return isset(self::IGNORABLE_TOKENS[$this->id]);
+    }
+
+    /**
+     * Return the textual content of the token.
+     */
+    public function __toString(): string {
+        return $this->text;
+    }
+
+    /**
+     * Tokenize the given source code and return an array of tokens.
+     *
+     * This performs certain canonicalizations to match the PHP 8.0 token format:
+     *  * Bad characters are represented using T_BAD_CHARACTER rather than omitted.
+     *  * T_COMMENT does not include trailing newlines, instead the newline is part of a following
+     *    T_WHITESPACE token.
+     *  * Namespaced names are represented using T_NAME_* tokens.
+     *
+     * @return static[]
+     */
+    public static function tokenize(string $code, int $flags = 0): array {
+        self::init();
+
+        $tokens = [];
+        $line = 1;
+        $pos = 0;
+        $origTokens = \token_get_all($code, $flags);
+
+        $numTokens = \count($origTokens);
+        for ($i = 0; $i < $numTokens; $i++) {
+            $token = $origTokens[$i];
+            if (\is_string($token)) {
+                if (\strlen($token) === 2) {
+                    // b" and B" are tokenized as single-char tokens, even though they aren't.
+                    $tokens[] = new static(\ord('"'), $token, $line, $pos);
+                    $pos += 2;
+                } else {
+                    $tokens[] = new static(\ord($token), $token, $line, $pos);
+                    $pos++;
+                }
+            } else {
+                $id = $token[0];
+                $text = $token[1];
+
+                // Emulate PHP 8.0 comment format, which does not include trailing whitespace anymore.
+                if ($id === \T_COMMENT && \substr($text, 0, 2) !== '/*' &&
+                    \preg_match('/(\r\n|\n|\r)$/D', $text, $matches)
+                ) {
+                    $trailingNewline = $matches[0];
+                    $text = \substr($text, 0, -\strlen($trailingNewline));
+                    $tokens[] = new static($id, $text, $line, $pos);
+                    $pos += \strlen($text);
+
+                    if ($i + 1 < $numTokens && $origTokens[$i + 1][0] === \T_WHITESPACE) {
+                        // Move trailing newline into following T_WHITESPACE token, if it already exists.
+                        $origTokens[$i + 1][1] = $trailingNewline . $origTokens[$i + 1][1];
+                        $origTokens[$i + 1][2]--;
+                    } else {
+                        // Otherwise, we need to create a new T_WHITESPACE token.
+                        $tokens[] = new static(\T_WHITESPACE, $trailingNewline, $line, $pos);
+                        $line++;
+                        $pos += \strlen($trailingNewline);
+                    }
+                    continue;
+                }
+
+                // Emulate PHP 8.0 T_NAME_* tokens, by combining sequences of T_NS_SEPARATOR and
+                // T_STRING into a single token.
+                if (($id === \T_NS_SEPARATOR || isset(self::$identifierTokens[$id]))) {
+                    $newText = $text;
+                    $lastWasSeparator = $id === \T_NS_SEPARATOR;
+                    for ($j = $i + 1; $j < $numTokens; $j++) {
+                        if ($lastWasSeparator) {
+                            if (!isset(self::$identifierTokens[$origTokens[$j][0]])) {
+                                break;
+                            }
+                            $lastWasSeparator = false;
+                        } else {
+                            if ($origTokens[$j][0] !== \T_NS_SEPARATOR) {
+                                break;
+                            }
+                            $lastWasSeparator = true;
+                        }
+                        $newText .= $origTokens[$j][1];
+                    }
+                    if ($lastWasSeparator) {
+                        // Trailing separator is not part of the name.
+                        $j--;
+                        $newText = \substr($newText, 0, -1);
+                    }
+                    if ($j > $i + 1) {
+                        if ($id === \T_NS_SEPARATOR) {
+                            $id = \T_NAME_FULLY_QUALIFIED;
+                        } elseif ($id === \T_NAMESPACE) {
+                            $id = \T_NAME_RELATIVE;
+                        } else {
+                            $id = \T_NAME_QUALIFIED;
+                        }
+                        $tokens[] = new static($id, $newText, $line, $pos);
+                        $pos += \strlen($newText);
+                        $i = $j - 1;
+                        continue;
+                    }
+                }
+
+                $tokens[] = new static($id, $text, $line, $pos);
+                $line += \substr_count($text, "\n");
+                $pos += \strlen($text);
+            }
+        }
+        return $tokens;
+    }
+
+    /** Initialize private static state needed by tokenize(). */
+    private static function init(): void {
+        if (isset(self::$identifierTokens)) {
+            return;
+        }
+
+        // Based on semi_reserved production.
+        self::$identifierTokens = \array_fill_keys([
+            \T_STRING,
+            \T_STATIC, \T_ABSTRACT, \T_FINAL, \T_PRIVATE, \T_PROTECTED, \T_PUBLIC, \T_READONLY,
+            \T_INCLUDE, \T_INCLUDE_ONCE, \T_EVAL, \T_REQUIRE, \T_REQUIRE_ONCE, \T_LOGICAL_OR, \T_LOGICAL_XOR, \T_LOGICAL_AND,
+            \T_INSTANCEOF, \T_NEW, \T_CLONE, \T_EXIT, \T_IF, \T_ELSEIF, \T_ELSE, \T_ENDIF, \T_ECHO, \T_DO, \T_WHILE,
+            \T_ENDWHILE, \T_FOR, \T_ENDFOR, \T_FOREACH, \T_ENDFOREACH, \T_DECLARE, \T_ENDDECLARE, \T_AS, \T_TRY, \T_CATCH,
+            \T_FINALLY, \T_THROW, \T_USE, \T_INSTEADOF, \T_GLOBAL, \T_VAR, \T_UNSET, \T_ISSET, \T_EMPTY, \T_CONTINUE, \T_GOTO,
+            \T_FUNCTION, \T_CONST, \T_RETURN, \T_PRINT, \T_YIELD, \T_LIST, \T_SWITCH, \T_ENDSWITCH, \T_CASE, \T_DEFAULT,
+            \T_BREAK, \T_ARRAY, \T_CALLABLE, \T_EXTENDS, \T_IMPLEMENTS, \T_NAMESPACE, \T_TRAIT, \T_INTERFACE, \T_CLASS,
+            \T_CLASS_C, \T_TRAIT_C, \T_FUNC_C, \T_METHOD_C, \T_LINE, \T_FILE, \T_DIR, \T_NS_C, \T_HALT_COMPILER, \T_FN,
+            \T_MATCH,
+        ], true);
+    }
+}

lib/PhpParser/Internal/TokenStream.php

@@ -0,0 +1,271 @@
+<?php declare(strict_types=1);
+
+namespace PhpParser\Internal;
+
+use PhpParser\Token;
+
+/**
+ * Provides operations on token streams, for use by pretty printer.
+ *
+ * @internal
+ */
+class TokenStream {
+    /** @var Token[] Tokens (in PhpToken::tokenize() format) */
+    private array $tokens;
+    /** @var int[] Map from position to indentation */
+    private array $indentMap;
+
+    /**
+     * Create token stream instance.
+     *
+     * @param Token[] $tokens Tokens in PhpToken::tokenize() format
+     */
+    public function __construct(array $tokens) {
+        $this->tokens = $tokens;
+        $this->indentMap = $this->calcIndentMap();
+    }
+
+    /**
+     * Whether the given position is immediately surrounded by parenthesis.
+     *
+     * @param int $startPos Start position
+     * @param int $endPos End position
+     */
+    public function haveParens(int $startPos, int $endPos): bool {
+        return $this->haveTokenImmediatelyBefore($startPos, '(')
+            && $this->haveTokenImmediatelyAfter($endPos, ')');
+    }
+
+    /**
+     * Whether the given position is immediately surrounded by braces.
+     *
+     * @param int $startPos Start position
+     * @param int $endPos End position
+     */
+    public function haveBraces(int $startPos, int $endPos): bool {
+        return ($this->haveTokenImmediatelyBefore($startPos, '{')
+                || $this->haveTokenImmediatelyBefore($startPos, T_CURLY_OPEN))
+            && $this->haveTokenImmediatelyAfter($endPos, '}');
+    }
+
+    /**
+     * Check whether the position is directly preceded by a certain token type.
+     *
+     * During this check whitespace and comments are skipped.
+     *
+     * @param int $pos Position before which the token should occur
+     * @param int|string $expectedTokenType Token to check for
+     *
+     * @return bool Whether the expected token was found
+     */
+    public function haveTokenImmediatelyBefore(int $pos, $expectedTokenType): bool {
+        $tokens = $this->tokens;
+        $pos--;
+        for (; $pos >= 0; $pos--) {
+            $token = $tokens[$pos];
+            if ($token->is($expectedTokenType)) {
+                return true;
+            }
+            if (!$token->isIgnorable()) {
+                break;
+            }
+        }
+        return false;
+    }
+
+    /**
+     * Check whether the position is directly followed by a certain token type.
+     *
+     * During this check whitespace and comments are skipped.
+     *
+     * @param int $pos Position after which the token should occur
+     * @param int|string $expectedTokenType Token to check for
+     *
+     * @return bool Whether the expected token was found
+     */
+    public function haveTokenImmediatelyAfter(int $pos, $expectedTokenType): bool {
+        $tokens = $this->tokens;
+        $pos++;
+        for ($c = \count($tokens); $pos < $c; $pos++) {
+            $token = $tokens[$pos];
+            if ($token->is($expectedTokenType)) {
+                return true;
+            }
+            if (!$token->isIgnorable()) {
+                break;
+            }
+        }
+        return false;
+    }
+
+    /** @param int|string|(int|string)[] $skipTokenType */
+    public function skipLeft(int $pos, $skipTokenType): int {
+        $tokens = $this->tokens;
+
+        $pos = $this->skipLeftWhitespace($pos);
+        if ($skipTokenType === \T_WHITESPACE) {
+            return $pos;
+        }
+
+        if (!$tokens[$pos]->is($skipTokenType)) {
+            // Shouldn't happen. The skip token MUST be there
+            throw new \Exception('Encountered unexpected token');
+        }
+        $pos--;
+
+        return $this->skipLeftWhitespace($pos);
+    }
+
+    /** @param int|string|(int|string)[] $skipTokenType */
+    public function skipRight(int $pos, $skipTokenType): int {
+        $tokens = $this->tokens;
+
+        $pos = $this->skipRightWhitespace($pos);
+        if ($skipTokenType === \T_WHITESPACE) {
+            return $pos;
+        }
+
+        if (!$tokens[$pos]->is($skipTokenType)) {
+            // Shouldn't happen. The skip token MUST be there
+            throw new \Exception('Encountered unexpected token');
+        }
+        $pos++;
+
+        return $this->skipRightWhitespace($pos);
+    }
+
+    /**
+     * Return first non-whitespace token position smaller or equal to passed position.
+     *
+     * @param int $pos Token position
+     * @return int Non-whitespace token position
+     */
+    public function skipLeftWhitespace(int $pos): int {
+        $tokens = $this->tokens;
+        for (; $pos >= 0; $pos--) {
+            if (!$tokens[$pos]->isIgnorable()) {
+                break;
+            }
+        }
+        return $pos;
+    }
+
+    /**
+     * Return first non-whitespace position greater or equal to passed position.
+     *
+     * @param int $pos Token position
+     * @return int Non-whitespace token position
+     */
+    public function skipRightWhitespace(int $pos): int {
+        $tokens = $this->tokens;
+        for ($count = \count($tokens); $pos < $count; $pos++) {
+            if (!$tokens[$pos]->isIgnorable()) {
+                break;
+            }
+        }
+        return $pos;
+    }
+
+    /** @param int|string|(int|string)[] $findTokenType */
+    public function findRight(int $pos, $findTokenType): int {
+        $tokens = $this->tokens;
+        for ($count = \count($tokens); $pos < $count; $pos++) {
+            if ($tokens[$pos]->is($findTokenType)) {
+                return $pos;
+            }
+        }
+        return -1;
+    }
+
+    /**
+     * Whether the given position range contains a certain token type.
+     *
+     * @param int $startPos Starting position (inclusive)
+     * @param int $endPos Ending position (exclusive)
+     * @param int|string $tokenType Token type to look for
+     * @return bool Whether the token occurs in the given range
+     */
+    public function haveTokenInRange(int $startPos, int $endPos, $tokenType): bool {
+        $tokens = $this->tokens;
+        for ($pos = $startPos; $pos < $endPos; $pos++) {
+            if ($tokens[$pos]->is($tokenType)) {
+                return true;
+            }
+        }
+        return false;
+    }
+
+    public function haveTagInRange(int $startPos, int $endPos): bool {
+        return $this->haveTokenInRange($startPos, $endPos, \T_OPEN_TAG)
+            || $this->haveTokenInRange($startPos, $endPos, \T_CLOSE_TAG);
+    }
+
+    /**
+     * Get indentation before token position.
+     *
+     * @param int $pos Token position
+     *
+     * @return int Indentation depth (in spaces)
+     */
+    public function getIndentationBefore(int $pos): int {
+        return $this->indentMap[$pos];
+    }
+
+    /**
+     * Get the code corresponding to a token offset range, optionally adjusted for indentation.
+     *
+     * @param int $from Token start position (inclusive)
+     * @param int $to Token end position (exclusive)
+     * @param int $indent By how much the code should be indented (can be negative as well)
+     *
+     * @return string Code corresponding to token range, adjusted for indentation
+     */
+    public function getTokenCode(int $from, int $to, int $indent): string {
+        $tokens = $this->tokens;
+        $result = '';
+        for ($pos = $from; $pos < $to; $pos++) {
+            $token = $tokens[$pos];
+            $id = $token->id;
+            $text = $token->text;
+            if ($id === \T_CONSTANT_ENCAPSED_STRING || $id === \T_ENCAPSED_AND_WHITESPACE) {
+                $result .= $text;
+            } else {
+                // TODO Handle non-space indentation
+                if ($indent < 0) {
+                    $result .= str_replace("\n" . str_repeat(" ", -$indent), "\n", $text);
+                } elseif ($indent > 0) {
+                    $result .= str_replace("\n", "\n" . str_repeat(" ", $indent), $text);
+                } else {
+                    $result .= $text;
+                }
+            }
+        }
+        return $result;
+    }
+
+    /**
+     * Precalculate the indentation at every token position.
+     *
+     * @return int[] Token position to indentation map
+     */
+    private function calcIndentMap(): array {
+        $indentMap = [];
+        $indent = 0;
+        foreach ($this->tokens as $token) {
+            $indentMap[] = $indent;
+
+            if ($token->id === \T_WHITESPACE) {
+                $content = $token->text;
+                $newlinePos = \strrpos($content, "\n");
+                if (false !== $newlinePos) {
+                    $indent = \strlen($content) - $newlinePos - 1;
+                }
+            }
+        }
+
+        // Add a sentinel for one past end of the file
+        $indentMap[] = $indent;
+
+        return $indentMap;
+    }
+}

lib/PhpParser/JsonDecoder.php

@@ -0,0 +1,108 @@
+<?php declare(strict_types=1);
+
+namespace PhpParser;
+
+class JsonDecoder {
+    /** @var \ReflectionClass<Node>[] Node type to reflection class map */
+    private array $reflectionClassCache;
+
+    /** @return mixed */
+    public function decode(string $json) {
+        $value = json_decode($json, true);
+        if (json_last_error()) {
+            throw new \RuntimeException('JSON decoding error: ' . json_last_error_msg());
+        }
+
+        return $this->decodeRecursive($value);
+    }
+
+    /**
+     * @param mixed $value
+     * @return mixed
+     */
+    private function decodeRecursive($value) {
+        if (\is_array($value)) {
+            if (isset($value['nodeType'])) {
+                if ($value['nodeType'] === 'Comment' || $value['nodeType'] === 'Comment_Doc') {
+                    return $this->decodeComment($value);
+                }
+                return $this->decodeNode($value);
+            }
+            return $this->decodeArray($value);
+        }
+        return $value;
+    }
+
+    private function decodeArray(array $array): array {
+        $decodedArray = [];
+        foreach ($array as $key => $value) {
+            $decodedArray[$key] = $this->decodeRecursive($value);
+        }
+        return $decodedArray;
+    }
+
+    private function decodeNode(array $value): Node {
+        $nodeType = $value['nodeType'];
+        if (!\is_string($nodeType)) {
+            throw new \RuntimeException('Node type must be a string');
+        }
+
+        $reflectionClass = $this->reflectionClassFromNodeType($nodeType);
+        $node = $reflectionClass->newInstanceWithoutConstructor();
+
+        if (isset($value['attributes'])) {
+            if (!\is_array($value['attributes'])) {
+                throw new \RuntimeException('Attributes must be an array');
+            }
+
+            $node->setAttributes($this->decodeArray($value['attributes']));
+        }
+
+        foreach ($value as $name => $subNode) {
+            if ($name === 'nodeType' || $name === 'attributes') {
+                continue;
+            }
+
+            $node->$name = $this->decodeRecursive($subNode);
+        }
+
+        return $node;
+    }
+
+    private function decodeComment(array $value): Comment {
+        $className = $value['nodeType'] === 'Comment' ? Comment::class : Comment\Doc::class;
+        if (!isset($value['text'])) {
+            throw new \RuntimeException('Comment must have text');
+        }
+
+        return new $className(
+            $value['text'],
+            $value['line'] ?? -1, $value['filePos'] ?? -1, $value['tokenPos'] ?? -1,
+            $value['endLine'] ?? -1, $value['endFilePos'] ?? -1, $value['endTokenPos'] ?? -1
+        );
+    }
+
+    /** @return \ReflectionClass<Node> */
+    private function reflectionClassFromNodeType(string $nodeType): \ReflectionClass {
+        if (!isset($this->reflectionClassCache[$nodeType])) {
+            $className = $this->classNameFromNodeType($nodeType);
+            $this->reflectionClassCache[$nodeType] = new \ReflectionClass($className);
+        }
+        return $this->reflectionClassCache[$nodeType];
+    }
+
+    /** @return class-string<Node> */
+    private function classNameFromNodeType(string $nodeType): string {
+        $className = 'PhpParser\\Node\\' . strtr($nodeType, '_', '\\');
+        if (class_exists($className)) {
+            return $className;
+        }
+
+        $className .= '_';
+        if (class_exists($className)) {
+            return $className;
+        }
+
+        throw new \RuntimeException("Unknown node type \"$nodeType\"");
+    }
+}

lib/PhpParser/Lexer.php

@@ -1,286 +1,116 @@
-<?php
+<?php declare(strict_types=1);
 
 namespace PhpParser;
 
-class Lexer
-{
-    protected $code;
-    protected $tokens;
-    protected $pos;
-    protected $line;
-    protected $filePos;
-
-    protected $tokenMap;
-    protected $dropTokens;
-
-    protected $usedAttributes;
+require __DIR__ . '/compatibility_tokens.php';
 
+class Lexer {
     /**
-     * Creates a Lexer.
+     * Tokenize the provided source code.
      *
-     * @param array $options Options array. Currently only the 'usedAttributes' option is supported,
-     *                       which is an array of attributes to add to the AST nodes. Possible attributes
-     *                       are: 'comments', 'startLine', 'endLine', 'startTokenPos', 'endTokenPos',
-     *                       'startFilePos', 'endFilePos'. The option defaults to the first three.
-     *                       For more info see getNextToken() docs.
+     * The token array is in the same format as provided by the PhpToken::tokenize() method in
+     * PHP 8.0. The tokens are instances of PhpParser\Token, to abstract over a polyfill
+     * implementation in earlier PHP version.
+     *
+     * The token array is terminated by a sentinel token with token ID 0.
+     * The token array does not discard any tokens (i.e. whitespace and comments are included).
+     * The token position attributes are against this token array.
+     *
+     * @param string $code The source code to tokenize.
+     * @param ErrorHandler|null $errorHandler Error handler to use for lexing errors. Defaults to
+     *                                        ErrorHandler\Throwing.
+     * @return Token[] Tokens
      */
-    public function __construct(array $options = array()) {
-        // map from internal tokens to PhpParser tokens
-        $this->tokenMap = $this->createTokenMap();
+    public function tokenize(string $code, ?ErrorHandler $errorHandler = null): array {
+        if (null === $errorHandler) {
+            $errorHandler = new ErrorHandler\Throwing();
+        }
 
-        // map of tokens to drop while lexing (the map is only used for isset lookup,
-        // that's why the value is simply set to 1; the value is never actually used.)
-        $this->dropTokens = array_fill_keys(array(T_WHITESPACE, T_OPEN_TAG), 1);
-
-        // the usedAttributes member is a map of the used attribute names to a dummy
-        // value (here "true")
-        $options += array(
-            'usedAttributes' => array('comments', 'startLine', 'endLine'),
-        );
-        $this->usedAttributes = array_fill_keys($options['usedAttributes'], true);
-    }
-
-    /**
-     * Initializes the lexer for lexing the provided source code.
-     *
-     * @param string $code The source code to lex
-     *
-     * @throws Error on lexing errors (unterminated comment or unexpected character)
-     */
-    public function startLexing($code) {
         $scream = ini_set('xdebug.scream', '0');
 
-        $this->resetErrors();
-        $this->tokens = @token_get_all($code);
-        $this->handleErrors();
+        $tokens = @Token::tokenize($code);
+        $this->postprocessTokens($tokens, $errorHandler);
 
         if (false !== $scream) {
             ini_set('xdebug.scream', $scream);
         }
 
-        $this->code = $code; // keep the code around for __halt_compiler() handling
-        $this->pos  = -1;
-        $this->line =  1;
-        $this->filePos = 0;
+        return $tokens;
     }
 
-    protected function resetErrors() {
-        // set error_get_last() to defined state by forcing an undefined variable error
-        set_error_handler(function() { return false; }, 0);
-        @$undefinedVariable;
-        restore_error_handler();
+    private function handleInvalidCharacter(Token $token, ErrorHandler $errorHandler): void {
+        $chr = $token->text;
+        if ($chr === "\0") {
+            // PHP cuts error message after null byte, so need special case
+            $errorMsg = 'Unexpected null byte';
+        } else {
+            $errorMsg = sprintf(
+                'Unexpected character "%s" (ASCII %d)', $chr, ord($chr)
+            );
+        }
+
+        $errorHandler->handleError(new Error($errorMsg, [
+            'startLine' => $token->line,
+            'endLine' => $token->line,
+            'startFilePos' => $token->pos,
+            'endFilePos' => $token->pos,
+        ]));
     }
 
-    protected function handleErrors() {
-        $error = error_get_last();
-
-        if (preg_match(
-            '~^Unterminated comment starting line ([0-9]+)$~',
-            $error['message'], $matches
-        )) {
-            throw new Error('Unterminated comment', (int) $matches[1]);
-        }
-
-        if (preg_match(
-            '~^Unexpected character in input:  \'(.)\' \(ASCII=([0-9]+)\)~s',
-            $error['message'], $matches
-        )) {
-            throw new Error(sprintf(
-                'Unexpected character "%s" (ASCII %d)',
-                $matches[1], $matches[2]
-            ));
-        }
-
-        // PHP cuts error message after null byte, so need special case
-        if (preg_match('~^Unexpected character in input:  \'$~', $error['message'])) {
-            throw new Error('Unexpected null byte');
-        }
+    private function isUnterminatedComment(Token $token): bool {
+        return $token->is([\T_COMMENT, \T_DOC_COMMENT])
+            && substr($token->text, 0, 2) === '/*'
+            && substr($token->text, -2) !== '*/';
     }
 
     /**
-     * Fetches the next token.
-     *
-     * The available attributes are determined by the 'usedAttributes' option, which can
-     * be specified in the constructor. The following attributes are supported:
-     *
-     *  * 'comments'      => Array of PhpParser\Comment or PhpParser\Comment\Doc instances,
-     *                       representing all comments that occurred between the previous
-     *                       non-discarded token and the current one.
-     *  * 'startLine'     => Line in which the node starts.
-     *  * 'endLine'       => Line in which the node ends.
-     *  * 'startTokenPos' => Offset into the token array of the first token in the node.
-     *  * 'endTokenPos'   => Offset into the token array of the last token in the node.
-     *  * 'startFilePos'  => Offset into the code string of the first character that is part of the node.
-     *  * 'endFilePos'    => Offset into the code string of the last character that is part of the node
-     *
-     * @param mixed $value           Variable to store token content in
-     * @param mixed $startAttributes Variable to store start attributes in
-     * @param mixed $endAttributes   Variable to store end attributes in
-     *
-     * @return int Token id
+     * @param list<Token> $tokens
      */
-    public function getNextToken(&$value = null, &$startAttributes = null, &$endAttributes = null) {
-        $startAttributes = array();
-        $endAttributes   = array();
+    protected function postprocessTokens(array &$tokens, ErrorHandler $errorHandler): void {
+        // This function reports errors (bad characters and unterminated comments) in the token
+        // array, and performs certain canonicalizations:
+        //  * Use PHP 8.1 T_AMPERSAND_NOT_FOLLOWED_BY_VAR_OR_VARARG and
+        //    T_AMPERSAND_FOLLOWED_BY_VAR_OR_VARARG tokens used to disambiguate intersection types.
+        //  * Add a sentinel token with ID 0.
 
-        while (1) {
-            if (isset($this->tokens[++$this->pos])) {
-                $token = $this->tokens[$this->pos];
-            } else {
-                // EOF token with ID 0
-                $token = "\0";
+        $numTokens = \count($tokens);
+        if ($numTokens === 0) {
+            // Empty input edge case: Just add the sentinel token.
+            $tokens[] = new Token(0, "\0", 1, 0);
+            return;
+        }
+
+        for ($i = 0; $i < $numTokens; $i++) {
+            $token = $tokens[$i];
+            if ($token->id === \T_BAD_CHARACTER) {
+                $this->handleInvalidCharacter($token, $errorHandler);
             }
 
-            if (isset($this->usedAttributes['startTokenPos'])) {
-                $startAttributes['startTokenPos'] = $this->pos;
-            }
-            if (isset($this->usedAttributes['startFilePos'])) {
-                $startAttributes['startFilePos'] = $this->filePos;
-            }
-
-            if (is_string($token)) {
-                // bug in token_get_all
-                if ('b"' === $token) {
-                    $value = 'b"';
-                    $this->filePos += 2;
-                    $id = ord('"');
-                } else {
-                    $value = $token;
-                    $this->filePos += 1;
-                    $id = ord($token);
-                }
-
-                if (isset($this->usedAttributes['startLine'])) {
-                    $startAttributes['startLine'] = $this->line;
-                }
-                if (isset($this->usedAttributes['endLine'])) {
-                    $endAttributes['endLine'] = $this->line;
-                }
-                if (isset($this->usedAttributes['endTokenPos'])) {
-                    $endAttributes['endTokenPos'] = $this->pos;
-                }
-                if (isset($this->usedAttributes['endFilePos'])) {
-                    $endAttributes['endFilePos'] = $this->filePos - 1;
-                }
-
-                return $id;
-            } else {
-                $this->line += substr_count($token[1], "\n");
-                $this->filePos += strlen($token[1]);
-
-                if (T_COMMENT === $token[0]) {
-                    if (isset($this->usedAttributes['comments'])) {
-                        $startAttributes['comments'][] = new Comment($token[1], $token[2]);
-                    }
-                } elseif (T_DOC_COMMENT === $token[0]) {
-                    if (isset($this->usedAttributes['comments'])) {
-                        $startAttributes['comments'][] = new Comment\Doc($token[1], $token[2]);
-                    }
-                } elseif (!isset($this->dropTokens[$token[0]])) {
-                    $value = $token[1];
-
-                    if (isset($this->usedAttributes['startLine'])) {
-                        $startAttributes['startLine'] = $token[2];
-                    }
-                    if (isset($this->usedAttributes['endLine'])) {
-                        $endAttributes['endLine'] = $this->line;
-                    }
-                    if (isset($this->usedAttributes['endTokenPos'])) {
-                        $endAttributes['endTokenPos'] = $this->pos;
-                    }
-                    if (isset($this->usedAttributes['endFilePos'])) {
-                        $endAttributes['endFilePos'] = $this->filePos - 1;
-                    }
-
-                    return $this->tokenMap[$token[0]];
+            if ($token->id === \ord('&')) {
+                $next = $i + 1;
+                while (isset($tokens[$next]) && $tokens[$next]->id === \T_WHITESPACE) {
+                    $next++;
                 }
+                $followedByVarOrVarArg = isset($tokens[$next]) &&
+                    $tokens[$next]->is([\T_VARIABLE, \T_ELLIPSIS]);
+                $token->id = $followedByVarOrVarArg
+                    ? \T_AMPERSAND_FOLLOWED_BY_VAR_OR_VARARG
+                    : \T_AMPERSAND_NOT_FOLLOWED_BY_VAR_OR_VARARG;
             }
         }
 
-        throw new \RuntimeException('Reached end of lexer loop');
-    }
-
-    /**
-     * Returns the token array for current code.
-     *
-     * The token array is in the same format as provided by the
-     * token_get_all() function and does not discard tokens (i.e.
-     * whitespace and comments are included). The token position
-     * attributes are against this token array.
-     *
-     * @return array Array of tokens in token_get_all() format
-     */
-    public function getTokens() {
-        return $this->tokens;
-    }
-
-    /**
-     * Handles __halt_compiler() by returning the text after it.
-     *
-     * @return string Remaining text
-     */
-    public function handleHaltCompiler() {
-        // text after T_HALT_COMPILER, still including ();
-        $textAfter = substr($this->code, $this->filePos);
-
-        // ensure that it is followed by ();
-        // this simplifies the situation, by not allowing any comments
-        // in between of the tokens.
-        if (!preg_match('~^\s*\(\s*\)\s*(?:;|\?>\r?\n?)~', $textAfter, $matches)) {
-            throw new Error('__HALT_COMPILER must be followed by "();"');
+        // Check for unterminated comment
+        $lastToken = $tokens[$numTokens - 1];
+        if ($this->isUnterminatedComment($lastToken)) {
+            $errorHandler->handleError(new Error('Unterminated comment', [
+                'startLine' => $lastToken->line,
+                'endLine' => $lastToken->getEndLine(),
+                'startFilePos' => $lastToken->pos,
+                'endFilePos' => $lastToken->getEndPos(),
+            ]));
         }
 
-        // prevent the lexer from returning any further tokens
-        $this->pos = count($this->tokens);
-
-        // return with (); removed
-        return (string) substr($textAfter, strlen($matches[0])); // (string) converts false to ''
-    }
-
-    /**
-     * Creates the token map.
-     *
-     * The token map maps the PHP internal token identifiers
-     * to the identifiers used by the Parser. Additionally it
-     * maps T_OPEN_TAG_WITH_ECHO to T_ECHO and T_CLOSE_TAG to ';'.
-     *
-     * @return array The token map
-     */
-    protected function createTokenMap() {
-        $tokenMap = array();
-
-        // 256 is the minimum possible token number, as everything below
-        // it is an ASCII value
-        for ($i = 256; $i < 1000; ++$i) {
-            if (T_DOUBLE_COLON === $i) {
-                // T_DOUBLE_COLON is equivalent to T_PAAMAYIM_NEKUDOTAYIM
-                $tokenMap[$i] = Parser::T_PAAMAYIM_NEKUDOTAYIM;
-            } elseif(T_OPEN_TAG_WITH_ECHO === $i) {
-                // T_OPEN_TAG_WITH_ECHO with dropped T_OPEN_TAG results in T_ECHO
-                $tokenMap[$i] = Parser::T_ECHO;
-            } elseif(T_CLOSE_TAG === $i) {
-                // T_CLOSE_TAG is equivalent to ';'
-                $tokenMap[$i] = ord(';');
-            } elseif ('UNKNOWN' !== $name = token_name($i)) {
-                if ('T_HASHBANG' === $name) {
-                    // HHVM uses a special token for #! hashbang lines
-                    $tokenMap[$i] = Parser::T_INLINE_HTML;
-                } else if (defined($name = 'PhpParser\Parser::' . $name)) {
-                    // Other tokens can be mapped directly
-                    $tokenMap[$i] = constant($name);
-                }
-            }
-        }
-
-        // HHVM uses a special token for numbers that overflow to double
-        if (defined('T_ONUMBER')) {
-            $tokenMap[T_ONUMBER] = Parser::T_DNUMBER;
-        }
-        // HHVM also has a separate token for the __COMPILER_HALT_OFFSET__ constant
-        if (defined('T_COMPILER_HALT_OFFSET')) {
-            $tokenMap[T_COMPILER_HALT_OFFSET] = Parser::T_STRING;
-        }
-
-        return $tokenMap;
+        // Add sentinel token.
+        $tokens[] = new Token(0, "\0", $lastToken->getEndLine(), $lastToken->getEndPos());
     }
 }

lib/PhpParser/Lexer/Emulative.php

@@ -1,231 +1,226 @@
-<?php
+<?php declare(strict_types=1);
 
 namespace PhpParser\Lexer;
 
-use PhpParser\Parser;
+use PhpParser\Error;
+use PhpParser\ErrorHandler;
+use PhpParser\Lexer;
+use PhpParser\Lexer\TokenEmulator\AttributeEmulator;
+use PhpParser\Lexer\TokenEmulator\EnumTokenEmulator;
+use PhpParser\Lexer\TokenEmulator\CoaleseEqualTokenEmulator;
+use PhpParser\Lexer\TokenEmulator\ExplicitOctalEmulator;
+use PhpParser\Lexer\TokenEmulator\FlexibleDocStringEmulator;
+use PhpParser\Lexer\TokenEmulator\FnTokenEmulator;
+use PhpParser\Lexer\TokenEmulator\MatchTokenEmulator;
+use PhpParser\Lexer\TokenEmulator\NullsafeTokenEmulator;
+use PhpParser\Lexer\TokenEmulator\NumericLiteralSeparatorEmulator;
+use PhpParser\Lexer\TokenEmulator\ReadonlyFunctionTokenEmulator;
+use PhpParser\Lexer\TokenEmulator\ReadonlyTokenEmulator;
+use PhpParser\Lexer\TokenEmulator\ReverseEmulator;
+use PhpParser\Lexer\TokenEmulator\TokenEmulator;
+use PhpParser\PhpVersion;
+use PhpParser\Token;
 
-/**
- * ATTENTION: This code is WRITE-ONLY. Do not try to read it.
- */
-class Emulative extends \PhpParser\Lexer
-{
-    protected $newKeywords;
-    protected $inObjectAccess;
+class Emulative extends Lexer {
+    /** @var array{int, string, string}[] Patches used to reverse changes introduced in the code */
+    private array $patches = [];
 
-    const T_ELLIPSIS   = 1001;
-    const T_POW        = 1002;
-    const T_POW_EQUAL  = 1003;
-    const T_COALESCE   = 1004;
-    const T_SPACESHIP  = 1005;
-    const T_YIELD_FROM = 1006;
+    /** @var list<TokenEmulator> */
+    private array $emulators = [];
 
-    const PHP_7_0 = '7.0.0dev';
-    const PHP_5_6 = '5.6.0rc1';
-    const PHP_5_5 = '5.5.0beta1';
-    const PHP_5_4 = '5.4.0beta1';
+    private PhpVersion $targetPhpVersion;
 
-    public function __construct(array $options = array()) {
-        parent::__construct($options);
+    private PhpVersion $hostPhpVersion;
 
-        $newKeywordsPerVersion = array(
-            self::PHP_5_5 => array(
-                'finally'       => Parser::T_FINALLY,
-                'yield'         => Parser::T_YIELD,
-            ),
-            self::PHP_5_4 => array(
-                'callable'      => Parser::T_CALLABLE,
-                'insteadof'     => Parser::T_INSTEADOF,
-                'trait'         => Parser::T_TRAIT,
-                '__trait__'     => Parser::T_TRAIT_C,
-            ),
-        );
+    /**
+     * @param PhpVersion|null $phpVersion PHP version to emulate. Defaults to newest supported.
+     */
+    public function __construct(?PhpVersion $phpVersion = null) {
+        $this->targetPhpVersion = $phpVersion ?? PhpVersion::getNewestSupported();
+        $this->hostPhpVersion = PhpVersion::getHostVersion();
 
-        $this->newKeywords = array();
-        foreach ($newKeywordsPerVersion as $version => $newKeywords) {
-            if (version_compare(PHP_VERSION, $version, '>=')) {
-                break;
+        $emulators = [
+            new MatchTokenEmulator(),
+            new NullsafeTokenEmulator(),
+            new AttributeEmulator(),
+            new EnumTokenEmulator(),
+            new ReadonlyTokenEmulator(),
+            new ExplicitOctalEmulator(),
+            new ReadonlyFunctionTokenEmulator(),
+        ];
+
+        // Collect emulators that are relevant for the PHP version we're running
+        // and the PHP version we're targeting for emulation.
+        foreach ($emulators as $emulator) {
+            $emulatorPhpVersion = $emulator->getPhpVersion();
+            if ($this->isForwardEmulationNeeded($emulatorPhpVersion)) {
+                $this->emulators[] = $emulator;
+            } elseif ($this->isReverseEmulationNeeded($emulatorPhpVersion)) {
+                $this->emulators[] = new ReverseEmulator($emulator);
             }
-
-            $this->newKeywords += $newKeywords;
         }
-
-        if (version_compare(PHP_VERSION, self::PHP_7_0, '>=')) {
-            return;
-        }
-        $this->tokenMap[self::T_COALESCE] = Parser::T_COALESCE;
-        $this->tokenMap[self::T_SPACESHIP] = Parser::T_SPACESHIP;
-        $this->tokenMap[self::T_YIELD_FROM] = Parser::T_YIELD_FROM;
-
-        if (version_compare(PHP_VERSION, self::PHP_5_6, '>=')) {
-            return;
-        }
-        $this->tokenMap[self::T_ELLIPSIS]  = Parser::T_ELLIPSIS;
-        $this->tokenMap[self::T_POW]       = Parser::T_POW;
-        $this->tokenMap[self::T_POW_EQUAL] = Parser::T_POW_EQUAL;
     }
 
-    public function startLexing($code) {
-        $this->inObjectAccess = false;
+    public function tokenize(string $code, ?ErrorHandler $errorHandler = null): array {
+        $emulators = array_filter($this->emulators, function ($emulator) use ($code) {
+            return $emulator->isEmulationNeeded($code);
+        });
 
-        $preprocessedCode = $this->preprocessCode($code);
-        parent::startLexing($preprocessedCode);
-        if ($preprocessedCode !== $code) {
-            $this->postprocessTokens();
+        if (empty($emulators)) {
+            // Nothing to emulate, yay
+            return parent::tokenize($code, $errorHandler);
         }
 
-        // Set code property back to the original code, so __halt_compiler()
-        // handling and (start|end)FilePos attributes use the correct offsets
-        $this->code = $code;
+        if ($errorHandler === null) {
+            $errorHandler = new ErrorHandler\Throwing();
+        }
+
+        $this->patches = [];
+        foreach ($emulators as $emulator) {
+            $code = $emulator->preprocessCode($code, $this->patches);
+        }
+
+        $collector = new ErrorHandler\Collecting();
+        $tokens = parent::tokenize($code, $collector);
+        $this->sortPatches();
+        $tokens = $this->fixupTokens($tokens);
+
+        $errors = $collector->getErrors();
+        if (!empty($errors)) {
+            $this->fixupErrors($errors);
+            foreach ($errors as $error) {
+                $errorHandler->handleError($error);
+            }
+        }
+
+        foreach ($emulators as $emulator) {
+            $tokens = $emulator->emulate($code, $tokens);
+        }
+
+        return $tokens;
     }
 
-    /*
-     * Replaces new features in the code by ~__EMU__{NAME}__{DATA}__~ sequences.
-     * ~LABEL~ is never valid PHP code, that's why we can (to some degree) safely
-     * use it here.
-     * Later when preprocessing the tokens these sequences will either be replaced
-     * by real tokens or replaced with their original content (e.g. if they occurred
-     * inside a string, i.e. a place where they don't have a special meaning).
+    private function isForwardEmulationNeeded(PhpVersion $emulatorPhpVersion): bool {
+        return $this->hostPhpVersion->older($emulatorPhpVersion)
+            && $this->targetPhpVersion->newerOrEqual($emulatorPhpVersion);
+    }
+
+    private function isReverseEmulationNeeded(PhpVersion $emulatorPhpVersion): bool {
+        return $this->hostPhpVersion->newerOrEqual($emulatorPhpVersion)
+            && $this->targetPhpVersion->older($emulatorPhpVersion);
+    }
+
+    private function sortPatches(): void {
+        // Patches may be contributed by different emulators.
+        // Make sure they are sorted by increasing patch position.
+        usort($this->patches, function ($p1, $p2) {
+            return $p1[0] <=> $p2[0];
+        });
+    }
+
+    /**
+     * @param list<Token> $tokens
+     * @return list<Token>
      */
-    protected function preprocessCode($code) {
-        if (version_compare(PHP_VERSION, self::PHP_7_0, '>=')) {
-            return $code;
+    private function fixupTokens(array $tokens): array {
+        if (\count($this->patches) === 0) {
+            return $tokens;
         }
 
-        $code = str_replace('??', '~__EMU__COALESCE__~', $code);
-        $code = str_replace('<=>', '~__EMU__SPACESHIP__~', $code);
-        $code = preg_replace_callback('(yield[ \n\r\t]+from)', function($matches) {
-            // Encoding $0 in order to preserve exact whitespace
-            return '~__EMU__YIELDFROM__' . bin2hex($matches[0]) . '__~';
-        }, $code);
+        // Load first patch
+        $patchIdx = 0;
+        list($patchPos, $patchType, $patchText) = $this->patches[$patchIdx];
 
-        if (version_compare(PHP_VERSION, self::PHP_5_6, '>=')) {
-            return $code;
-        }
-
-        $code = str_replace('...', '~__EMU__ELLIPSIS__~', $code);
-        $code = preg_replace('((?<!/)\*\*=)', '~__EMU__POWEQUAL__~', $code);
-        $code = preg_replace('((?<!/)\*\*(?!/))', '~__EMU__POW__~', $code);
-
-        if (version_compare(PHP_VERSION, self::PHP_5_4, '>=')) {
-            return $code;
-        }
-
-        // binary notation (0b010101101001...)
-        return preg_replace('(\b0b[01]+\b)', '~__EMU__BINARY__$0__~', $code);
-    }
-
-    /*
-     * Replaces the ~__EMU__...~ sequences with real tokens or their original
-     * value.
-     */
-    protected function postprocessTokens() {
-        // we need to manually iterate and manage a count because we'll change
-        // the tokens array on the way
-        for ($i = 0, $c = count($this->tokens); $i < $c; ++$i) {
-            // first check that the following tokens are of form ~LABEL~,
-            // then match the __EMU__... sequence.
-            if ('~' === $this->tokens[$i]
-                && isset($this->tokens[$i + 2])
-                && '~' === $this->tokens[$i + 2]
-                && T_STRING === $this->tokens[$i + 1][0]
-                && preg_match('(^__EMU__([A-Z]++)__(?:([A-Za-z0-9]++)__)?$)', $this->tokens[$i + 1][1], $matches)
-            ) {
-                if ('BINARY' === $matches[1]) {
-                    // the binary number can either be an integer or a double, so return a LNUMBER
-                    // or DNUMBER respectively
-                    $isInt = is_int(bindec($matches[2]));
-                    $replace = array(
-                        array($isInt ? T_LNUMBER : T_DNUMBER, $matches[2], $this->tokens[$i + 1][2])
+        // We use a manual loop over the tokens, because we modify the array on the fly
+        $posDelta = 0;
+        $lineDelta = 0;
+        for ($i = 0, $c = \count($tokens); $i < $c; $i++) {
+            $token = $tokens[$i];
+            $pos = $token->pos;
+            $token->pos += $posDelta;
+            $token->line += $lineDelta;
+            $localPosDelta = 0;
+            $len = \strlen($token->text);
+            while ($patchPos >= $pos && $patchPos < $pos + $len) {
+                $patchTextLen = \strlen($patchText);
+                if ($patchType === 'remove') {
+                    if ($patchPos === $pos && $patchTextLen === $len) {
+                        // Remove token entirely
+                        array_splice($tokens, $i, 1, []);
+                        $i--;
+                        $c--;
+                    } else {
+                        // Remove from token string
+                        $token->text = substr_replace(
+                            $token->text, '', $patchPos - $pos + $localPosDelta, $patchTextLen
+                        );
+                        $localPosDelta -= $patchTextLen;
+                    }
+                    $lineDelta -= \substr_count($patchText, "\n");
+                } elseif ($patchType === 'add') {
+                    // Insert into the token string
+                    $token->text = substr_replace(
+                        $token->text, $patchText, $patchPos - $pos + $localPosDelta, 0
                     );
-                } else if ('ELLIPSIS' === $matches[1]) {
-                    $replace = array(
-                        array(self::T_ELLIPSIS, '...', $this->tokens[$i + 1][2])
-                    );
-                } else if ('POW' === $matches[1]) {
-                    $replace = array(
-                        array(self::T_POW, '**', $this->tokens[$i + 1][2])
-                    );
-                } else if ('POWEQUAL' === $matches[1]) {
-                    $replace = array(
-                        array(self::T_POW_EQUAL, '**=', $this->tokens[$i + 1][2])
-                    );
-                } else if ('COALESCE' === $matches[1]) {
-                    $replace = array(
-                        array(self::T_COALESCE, '??', $this->tokens[$i + 1][2])
-                    );
-                } else if ('SPACESHIP' === $matches[1]) {
-                    $replace = array(
-                        array(self::T_SPACESHIP, '<=>', $this->tokens[$i + 1][2]),
-                    );
-                } else if ('YIELDFROM' === $matches[1]) {
-                    $content = $this->hex2bin($matches[2]);
-                    $replace = array(
-                        array(self::T_YIELD_FROM, $content, $this->tokens[$i + 1][2] - substr_count($content, "\n"))
+                    $localPosDelta += $patchTextLen;
+                    $lineDelta += \substr_count($patchText, "\n");
+                } elseif ($patchType === 'replace') {
+                    // Replace inside the token string
+                    $token->text = substr_replace(
+                        $token->text, $patchText, $patchPos - $pos + $localPosDelta, $patchTextLen
                     );
                 } else {
-                    throw new \RuntimeException('Invalid __EMU__ sequence');
+                    assert(false);
                 }
 
-                array_splice($this->tokens, $i, 3, $replace);
-                $c -= 3 - count($replace);
-            // for multichar tokens (e.g. strings) replace any ~__EMU__...~ sequences
-            // in their content with the original character sequence
-            } elseif (is_array($this->tokens[$i])
-                      && 0 !== strpos($this->tokens[$i][1], '__EMU__')
-            ) {
-                $this->tokens[$i][1] = preg_replace_callback(
-                    '(~__EMU__([A-Z]++)__(?:([A-Za-z0-9]++)__)?~)',
-                    array($this, 'restoreContentCallback'),
-                    $this->tokens[$i][1]
-                );
+                // Fetch the next patch
+                $patchIdx++;
+                if ($patchIdx >= \count($this->patches)) {
+                    // No more patches. However, we still need to adjust position.
+                    $patchPos = \PHP_INT_MAX;
+                    break;
+                }
+
+                list($patchPos, $patchType, $patchText) = $this->patches[$patchIdx];
             }
+
+            $posDelta += $localPosDelta;
         }
+        return $tokens;
     }
 
-    /*
-     * This method is a callback for restoring EMU sequences in
-     * multichar tokens (like strings) to their original value.
+    /**
+     * Fixup line and position information in errors.
+     *
+     * @param Error[] $errors
      */
-    public function restoreContentCallback(array $matches) {
-        if ('BINARY' === $matches[1]) {
-            return $matches[2];
-        } else if ('ELLIPSIS' === $matches[1]) {
-            return '...';
-        } else if ('POW' === $matches[1]) {
-            return '**';
-        } else if ('POWEQUAL' === $matches[1]) {
-            return '**=';
-        } else if ('COALESCE' === $matches[1]) {
-            return '??';
-        } else if ('SPACESHIP' === $matches[1]) {
-            return '<=>';
-        } else if ('YIELDFROM' === $matches[1]) {
-            return $this->hex2bin($matches[2]);
-        } else {
-            return $matches[0];
-        }
-    }
+    private function fixupErrors(array $errors): void {
+        foreach ($errors as $error) {
+            $attrs = $error->getAttributes();
 
-    private function hex2bin($str) {
-        // TODO Drop when removing support for PHP 5.3
-        return pack('H*', $str);
-    }
+            $posDelta = 0;
+            $lineDelta = 0;
+            foreach ($this->patches as $patch) {
+                list($patchPos, $patchType, $patchText) = $patch;
+                if ($patchPos >= $attrs['startFilePos']) {
+                    // No longer relevant
+                    break;
+                }
 
-    public function getNextToken(&$value = null, &$startAttributes = null, &$endAttributes = null) {
-        $token = parent::getNextToken($value, $startAttributes, $endAttributes);
-
-        // replace new keywords by their respective tokens. This is not done
-        // if we currently are in an object access (e.g. in $obj->namespace
-        // "namespace" stays a T_STRING tokens and isn't converted to T_NAMESPACE)
-        if (Parser::T_STRING === $token && !$this->inObjectAccess) {
-            if (isset($this->newKeywords[strtolower($value)])) {
-                return $this->newKeywords[strtolower($value)];
+                if ($patchType === 'add') {
+                    $posDelta += strlen($patchText);
+                    $lineDelta += substr_count($patchText, "\n");
+                } elseif ($patchType === 'remove') {
+                    $posDelta -= strlen($patchText);
+                    $lineDelta -= substr_count($patchText, "\n");
+                }
             }
-        } else {
-            // keep track of whether we currently are in an object access (after ->)
-            $this->inObjectAccess = Parser::T_OBJECT_OPERATOR === $token;
-        }
 
-        return $token;
+            $attrs['startFilePos'] += $posDelta;
+            $attrs['endFilePos'] += $posDelta;
+            $attrs['startLine'] += $lineDelta;
+            $attrs['endLine'] += $lineDelta;
+            $error->setAttributes($attrs);
+        }
     }
 }

lib/PhpParser/Lexer/TokenEmulator/AttributeEmulator.php

@@ -0,0 +1,49 @@
+<?php declare(strict_types=1);
+
+namespace PhpParser\Lexer\TokenEmulator;
+
+use PhpParser\PhpVersion;
+use PhpParser\Token;
+
+final class AttributeEmulator extends TokenEmulator {
+    public function getPhpVersion(): PhpVersion {
+        return PhpVersion::fromComponents(8, 0);
+    }
+
+    public function isEmulationNeeded(string $code): bool {
+        return strpos($code, '#[') !== false;
+    }
+
+    public function emulate(string $code, array $tokens): array {
+        // We need to manually iterate and manage a count because we'll change
+        // the tokens array on the way.
+        for ($i = 0, $c = count($tokens); $i < $c; ++$i) {
+            $token = $tokens[$i];
+            if ($token->text === '#' && isset($tokens[$i + 1]) && $tokens[$i + 1]->text === '[') {
+                array_splice($tokens, $i, 2, [
+                    new Token(\T_ATTRIBUTE, '#[', $token->line, $token->pos),
+                ]);
+                $c--;
+                continue;
+            }
+        }
+
+        return $tokens;
+    }
+
+    public function reverseEmulate(string $code, array $tokens): array {
+        // TODO
+        return $tokens;
+    }
+
+    public function preprocessCode(string $code, array &$patches): string {
+        $pos = 0;
+        while (false !== $pos = strpos($code, '#[', $pos)) {
+            // Replace #[ with %[
+            $code[$pos] = '%';
+            $patches[] = [$pos, 'replace', '#'];
+            $pos += 2;
+        }
+        return $code;
+    }
+}

lib/PhpParser/Lexer/TokenEmulator/EnumTokenEmulator.php

@@ -0,0 +1,26 @@
+<?php declare(strict_types=1);
+
+namespace PhpParser\Lexer\TokenEmulator;
+
+use PhpParser\PhpVersion;
+
+final class EnumTokenEmulator extends KeywordEmulator {
+    public function getPhpVersion(): PhpVersion {
+        return PhpVersion::fromComponents(8, 1);
+    }
+
+    public function getKeywordString(): string {
+        return 'enum';
+    }
+
+    public function getKeywordToken(): int {
+        return \T_ENUM;
+    }
+
+    protected function isKeywordContext(array $tokens, int $pos): bool {
+        return parent::isKeywordContext($tokens, $pos)
+            && isset($tokens[$pos + 2])
+            && $tokens[$pos + 1]->id === \T_WHITESPACE
+            && $tokens[$pos + 2]->id === \T_STRING;
+    }
+}

lib/PhpParser/Lexer/TokenEmulator/ExplicitOctalEmulator.php

@@ -0,0 +1,45 @@
+<?php declare(strict_types=1);
+
+namespace PhpParser\Lexer\TokenEmulator;
+
+use PhpParser\PhpVersion;
+use PhpParser\Token;
+
+class ExplicitOctalEmulator extends TokenEmulator {
+    public function getPhpVersion(): PhpVersion {
+        return PhpVersion::fromComponents(8, 1);
+    }
+
+    public function isEmulationNeeded(string $code): bool {
+        return strpos($code, '0o') !== false || strpos($code, '0O') !== false;
+    }
+
+    public function emulate(string $code, array $tokens): array {
+        for ($i = 0, $c = count($tokens); $i < $c; ++$i) {
+            $token = $tokens[$i];
+            if ($token->id == \T_LNUMBER && $token->text === '0' &&
+                isset($tokens[$i + 1]) && $tokens[$i + 1]->id == \T_STRING &&
+                preg_match('/[oO][0-7]+(?:_[0-7]+)*/', $tokens[$i + 1]->text)
+            ) {
+                $tokenKind = $this->resolveIntegerOrFloatToken($tokens[$i + 1]->text);
+                array_splice($tokens, $i, 2, [
+                    new Token($tokenKind, '0' . $tokens[$i + 1]->text, $token->line, $token->pos),
+                ]);
+                $c--;
+            }
+        }
+        return $tokens;
+    }
+
+    private function resolveIntegerOrFloatToken(string $str): int {
+        $str = substr($str, 1);
+        $str = str_replace('_', '', $str);
+        $num = octdec($str);
+        return is_float($num) ? \T_DNUMBER : \T_LNUMBER;
+    }
+
+    public function reverseEmulate(string $code, array $tokens): array {
+        // Explicit octals were not legal code previously, don't bother.
+        return $tokens;
+    }
+}

lib/PhpParser/Lexer/TokenEmulator/KeywordEmulator.php

@@ -0,0 +1,56 @@
+<?php declare(strict_types=1);
+
+namespace PhpParser\Lexer\TokenEmulator;
+
+use PhpParser\Token;
+
+abstract class KeywordEmulator extends TokenEmulator {
+    abstract public function getKeywordString(): string;
+    abstract public function getKeywordToken(): int;
+
+    public function isEmulationNeeded(string $code): bool {
+        return strpos(strtolower($code), $this->getKeywordString()) !== false;
+    }
+
+    /** @param Token[] $tokens */
+    protected function isKeywordContext(array $tokens, int $pos): bool {
+        $previousNonSpaceToken = $this->getPreviousNonSpaceToken($tokens, $pos);
+        return $previousNonSpaceToken === null || $previousNonSpaceToken->id !== \T_OBJECT_OPERATOR;
+    }
+
+    public function emulate(string $code, array $tokens): array {
+        $keywordString = $this->getKeywordString();
+        foreach ($tokens as $i => $token) {
+            if ($token->id === T_STRING && strtolower($token->text) === $keywordString
+                    && $this->isKeywordContext($tokens, $i)) {
+                $token->id = $this->getKeywordToken();
+            }
+        }
+
+        return $tokens;
+    }
+
+    /** @param Token[] $tokens */
+    private function getPreviousNonSpaceToken(array $tokens, int $start): ?Token {
+        for ($i = $start - 1; $i >= 0; --$i) {
+            if ($tokens[$i]->id === T_WHITESPACE) {
+                continue;
+            }
+
+            return $tokens[$i];
+        }
+
+        return null;
+    }
+
+    public function reverseEmulate(string $code, array $tokens): array {
+        $keywordToken = $this->getKeywordToken();
+        foreach ($tokens as $token) {
+            if ($token->id === $keywordToken) {
+                $token->id = \T_STRING;
+            }
+        }
+
+        return $tokens;
+    }
+}

lib/PhpParser/Lexer/TokenEmulator/MatchTokenEmulator.php

@@ -0,0 +1,19 @@
+<?php declare(strict_types=1);
+
+namespace PhpParser\Lexer\TokenEmulator;
+
+use PhpParser\PhpVersion;
+
+final class MatchTokenEmulator extends KeywordEmulator {
+    public function getPhpVersion(): PhpVersion {
+        return PhpVersion::fromComponents(8, 0);
+    }
+
+    public function getKeywordString(): string {
+        return 'match';
+    }
+
+    public function getKeywordToken(): int {
+        return \T_MATCH;
+    }
+}

lib/PhpParser/Lexer/TokenEmulator/NullsafeTokenEmulator.php

@@ -0,0 +1,60 @@
+<?php declare(strict_types=1);
+
+namespace PhpParser\Lexer\TokenEmulator;
+
+use PhpParser\PhpVersion;
+use PhpParser\Token;
+
+final class NullsafeTokenEmulator extends TokenEmulator {
+    public function getPhpVersion(): PhpVersion {
+        return PhpVersion::fromComponents(8, 0);
+    }
+
+    public function isEmulationNeeded(string $code): bool {
+        return strpos($code, '?->') !== false;
+    }
+
+    public function emulate(string $code, array $tokens): array {
+        // We need to manually iterate and manage a count because we'll change
+        // the tokens array on the way
+        for ($i = 0, $c = count($tokens); $i < $c; ++$i) {
+            $token = $tokens[$i];
+            if ($token->text === '?' && isset($tokens[$i + 1]) && $tokens[$i + 1]->id === \T_OBJECT_OPERATOR) {
+                array_splice($tokens, $i, 2, [
+                    new Token(\T_NULLSAFE_OBJECT_OPERATOR, '?->', $token->line, $token->pos),
+                ]);
+                $c--;
+                continue;
+            }
+
+            // Handle ?-> inside encapsed string.
+            if ($token->id === \T_ENCAPSED_AND_WHITESPACE && isset($tokens[$i - 1])
+                && $tokens[$i - 1]->id === \T_VARIABLE
+                && preg_match('/^\?->([a-zA-Z_\x80-\xff][a-zA-Z0-9_\x80-\xff]*)/', $token->text, $matches)
+            ) {
+                $replacement = [
+                    new Token(\T_NULLSAFE_OBJECT_OPERATOR, '?->', $token->line, $token->pos),
+                    new Token(\T_STRING, $matches[1], $token->line, $token->pos + 3),
+                ];
+                $matchLen = \strlen($matches[0]);
+                if ($matchLen !== \strlen($token->text)) {
+                    $replacement[] = new Token(
+                        \T_ENCAPSED_AND_WHITESPACE,
+                        \substr($token->text, $matchLen),
+                        $token->line, $token->pos + $matchLen
+                    );
+                }
+                array_splice($tokens, $i, 1, $replacement);
+                $c += \count($replacement) - 1;
+                continue;
+            }
+        }
+
+        return $tokens;
+    }
+
+    public function reverseEmulate(string $code, array $tokens): array {
+        // ?-> was not valid code previously, don't bother.
+        return $tokens;
+    }
+}

lib/PhpParser/Lexer/TokenEmulator/ReadonlyFunctionTokenEmulator.php

@@ -0,0 +1,31 @@
+<?php declare(strict_types=1);
+
+namespace PhpParser\Lexer\TokenEmulator;
+
+use PhpParser\PhpVersion;
+
+/*
+ * In PHP 8.1, "readonly(" was special cased in the lexer in order to support functions with
+ * name readonly. In PHP 8.2, this may conflict with readonly properties having a DNF type. For
+ * this reason, PHP 8.2 instead treats this as T_READONLY and then handles it specially in the
+ * parser. This emulator only exists to handle this special case, which is skipped by the
+ * PHP 8.1 ReadonlyTokenEmulator.
+ */
+class ReadonlyFunctionTokenEmulator extends KeywordEmulator {
+    public function getKeywordString(): string {
+        return 'readonly';
+    }
+
+    public function getKeywordToken(): int {
+        return \T_READONLY;
+    }
+
+    public function getPhpVersion(): PhpVersion {
+        return PhpVersion::fromComponents(8, 2);
+    }
+
+    public function reverseEmulate(string $code, array $tokens): array {
+        // Don't bother
+        return $tokens;
+    }
+}

lib/PhpParser/Lexer/TokenEmulator/ReadonlyTokenEmulator.php

@@ -0,0 +1,31 @@
+<?php declare(strict_types=1);
+
+namespace PhpParser\Lexer\TokenEmulator;
+
+use PhpParser\PhpVersion;
+
+final class ReadonlyTokenEmulator extends KeywordEmulator {
+    public function getPhpVersion(): PhpVersion {
+        return PhpVersion::fromComponents(8, 1);
+    }
+
+    public function getKeywordString(): string {
+        return 'readonly';
+    }
+
+    public function getKeywordToken(): int {
+        return \T_READONLY;
+    }
+
+    protected function isKeywordContext(array $tokens, int $pos): bool {
+        if (!parent::isKeywordContext($tokens, $pos)) {
+            return false;
+        }
+        // Support "function readonly("
+        return !(isset($tokens[$pos + 1]) &&
+                 ($tokens[$pos + 1]->text === '(' ||
+                  ($tokens[$pos + 1]->id === \T_WHITESPACE &&
+                   isset($tokens[$pos + 2]) &&
+                   $tokens[$pos + 2]->text === '(')));
+    }
+}

lib/PhpParser/Lexer/TokenEmulator/ReverseEmulator.php

@@ -0,0 +1,37 @@
+<?php declare(strict_types=1);
+
+namespace PhpParser\Lexer\TokenEmulator;
+
+use PhpParser\PhpVersion;
+
+/**
+ * Reverses emulation direction of the inner emulator.
+ */
+final class ReverseEmulator extends TokenEmulator {
+    /** @var TokenEmulator Inner emulator */
+    private TokenEmulator $emulator;
+
+    public function __construct(TokenEmulator $emulator) {
+        $this->emulator = $emulator;
+    }
+
+    public function getPhpVersion(): PhpVersion {
+        return $this->emulator->getPhpVersion();
+    }
+
+    public function isEmulationNeeded(string $code): bool {
+        return $this->emulator->isEmulationNeeded($code);
+    }
+
+    public function emulate(string $code, array $tokens): array {
+        return $this->emulator->reverseEmulate($code, $tokens);
+    }
+
+    public function reverseEmulate(string $code, array $tokens): array {
+        return $this->emulator->emulate($code, $tokens);
+    }
+
+    public function preprocessCode(string $code, array &$patches): string {
+        return $code;
+    }
+}

lib/PhpParser/Lexer/TokenEmulator/TokenEmulator.php

@@ -0,0 +1,30 @@
+<?php declare(strict_types=1);
+
+namespace PhpParser\Lexer\TokenEmulator;
+
+use PhpParser\PhpVersion;
+use PhpParser\Token;
+
+/** @internal */
+abstract class TokenEmulator {
+    abstract public function getPhpVersion(): PhpVersion;
+
+    abstract public function isEmulationNeeded(string $code): bool;
+
+    /**
+     * @param Token[] $tokens Original tokens
+     * @return Token[] Modified Tokens
+     */
+    abstract public function emulate(string $code, array $tokens): array;
+
+    /**
+     * @param Token[] $tokens Original tokens
+     * @return Token[] Modified Tokens
+     */
+    abstract public function reverseEmulate(string $code, array $tokens): array;
+
+    /** @param array{int, string, string}[] $patches */
+    public function preprocessCode(string $code, array &$patches): string {
+        return $code;
+    }
+}

lib/PhpParser/Modifiers.php

@@ -0,0 +1,69 @@
+<?php declare(strict_types=1);
+
+namespace PhpParser;
+
+/**
+ * Modifiers used (as a bit mask) by various flags subnodes, for example on classes, functions,
+ * properties and constants.
+ */
+final class Modifiers {
+    public const PUBLIC    =  1;
+    public const PROTECTED =  2;
+    public const PRIVATE   =  4;
+    public const STATIC    =  8;
+    public const ABSTRACT  = 16;
+    public const FINAL     = 32;
+    public const READONLY  = 64;
+
+    public const VISIBILITY_MASK = 1 | 2 | 4;
+
+    /**
+     * @internal
+     */
+    public static function verifyClassModifier(int $a, int $b): void {
+        if ($a & Modifiers::ABSTRACT && $b & Modifiers::ABSTRACT) {
+            throw new Error('Multiple abstract modifiers are not allowed');
+        }
+
+        if ($a & Modifiers::FINAL && $b & Modifiers::FINAL) {
+            throw new Error('Multiple final modifiers are not allowed');
+        }
+
+        if ($a & Modifiers::READONLY && $b & Modifiers::READONLY) {
+            throw new Error('Multiple readonly modifiers are not allowed');
+        }
+
+        if ($a & 48 && $b & 48) {
+            throw new Error('Cannot use the final modifier on an abstract class');
+        }
+    }
+
+    /**
+     * @internal
+     */
+    public static function verifyModifier(int $a, int $b): void {
+        if ($a & Modifiers::VISIBILITY_MASK && $b & Modifiers::VISIBILITY_MASK) {
+            throw new Error('Multiple access type modifiers are not allowed');
+        }
+
+        if ($a & Modifiers::ABSTRACT && $b & Modifiers::ABSTRACT) {
+            throw new Error('Multiple abstract modifiers are not allowed');
+        }
+
+        if ($a & Modifiers::STATIC && $b & Modifiers::STATIC) {
+            throw new Error('Multiple static modifiers are not allowed');
+        }
+
+        if ($a & Modifiers::FINAL && $b & Modifiers::FINAL) {
+            throw new Error('Multiple final modifiers are not allowed');
+        }
+
+        if ($a & Modifiers::READONLY && $b & Modifiers::READONLY) {
+            throw new Error('Multiple readonly modifiers are not allowed');
+        }
+
+        if ($a & 48 && $b & 48) {
+            throw new Error('Cannot use the final modifier on an abstract class member');
+        }
+    }
+}

lib/PhpParser/NameContext.php

@@ -0,0 +1,284 @@
+<?php declare(strict_types=1);
+
+namespace PhpParser;
+
+use PhpParser\Node\Name;
+use PhpParser\Node\Name\FullyQualified;
+use PhpParser\Node\Stmt;
+
+class NameContext {
+    /** @var null|Name Current namespace */
+    protected ?Name $namespace;
+
+    /** @var Name[][] Map of format [aliasType => [aliasName => originalName]] */
+    protected array $aliases = [];
+
+    /** @var Name[][] Same as $aliases but preserving original case */
+    protected array $origAliases = [];
+
+    /** @var ErrorHandler Error handler */
+    protected ErrorHandler $errorHandler;
+
+    /**
+     * Create a name context.
+     *
+     * @param ErrorHandler $errorHandler Error handling used to report errors
+     */
+    public function __construct(ErrorHandler $errorHandler) {
+        $this->errorHandler = $errorHandler;
+    }
+
+    /**
+     * Start a new namespace.
+     *
+     * This also resets the alias table.
+     *
+     * @param Name|null $namespace Null is the global namespace
+     */
+    public function startNamespace(?Name $namespace = null): void {
+        $this->namespace = $namespace;
+        $this->origAliases = $this->aliases = [
+            Stmt\Use_::TYPE_NORMAL   => [],
+            Stmt\Use_::TYPE_FUNCTION => [],
+            Stmt\Use_::TYPE_CONSTANT => [],
+        ];
+    }
+
+    /**
+     * Add an alias / import.
+     *
+     * @param Name $name Original name
+     * @param string $aliasName Aliased name
+     * @param Stmt\Use_::TYPE_* $type One of Stmt\Use_::TYPE_*
+     * @param array<string, mixed> $errorAttrs Attributes to use to report an error
+     */
+    public function addAlias(Name $name, string $aliasName, int $type, array $errorAttrs = []): void {
+        // Constant names are case sensitive, everything else case insensitive
+        if ($type === Stmt\Use_::TYPE_CONSTANT) {
+            $aliasLookupName = $aliasName;
+        } else {
+            $aliasLookupName = strtolower($aliasName);
+        }
+
+        if (isset($this->aliases[$type][$aliasLookupName])) {
+            $typeStringMap = [
+                Stmt\Use_::TYPE_NORMAL   => '',
+                Stmt\Use_::TYPE_FUNCTION => 'function ',
+                Stmt\Use_::TYPE_CONSTANT => 'const ',
+            ];
+
+            $this->errorHandler->handleError(new Error(
+                sprintf(
+                    'Cannot use %s%s as %s because the name is already in use',
+                    $typeStringMap[$type], $name, $aliasName
+                ),
+                $errorAttrs
+            ));
+            return;
+        }
+
+        $this->aliases[$type][$aliasLookupName] = $name;
+        $this->origAliases[$type][$aliasName] = $name;
+    }
+
+    /**
+     * Get current namespace.
+     *
+     * @return null|Name Namespace (or null if global namespace)
+     */
+    public function getNamespace(): ?Name {
+        return $this->namespace;
+    }
+
+    /**
+     * Get resolved name.
+     *
+     * @param Name $name Name to resolve
+     * @param Stmt\Use_::TYPE_* $type One of Stmt\Use_::TYPE_{FUNCTION|CONSTANT}
+     *
+     * @return null|Name Resolved name, or null if static resolution is not possible
+     */
+    public function getResolvedName(Name $name, int $type): ?Name {
+        // don't resolve special class names
+        if ($type === Stmt\Use_::TYPE_NORMAL && $name->isSpecialClassName()) {
+            if (!$name->isUnqualified()) {
+                $this->errorHandler->handleError(new Error(
+                    sprintf("'\\%s' is an invalid class name", $name->toString()),
+                    $name->getAttributes()
+                ));
+            }
+            return $name;
+        }
+
+        // fully qualified names are already resolved
+        if ($name->isFullyQualified()) {
+            return $name;
+        }
+
+        // Try to resolve aliases
+        if (null !== $resolvedName = $this->resolveAlias($name, $type)) {
+            return $resolvedName;
+        }
+
+        if ($type !== Stmt\Use_::TYPE_NORMAL && $name->isUnqualified()) {
+            if (null === $this->namespace) {
+                // outside of a namespace unaliased unqualified is same as fully qualified
+                return new FullyQualified($name, $name->getAttributes());
+            }
+
+            // Cannot resolve statically
+            return null;
+        }
+
+        // if no alias exists prepend current namespace
+        return FullyQualified::concat($this->namespace, $name, $name->getAttributes());
+    }
+
+    /**
+     * Get resolved class name.
+     *
+     * @param Name $name Class ame to resolve
+     *
+     * @return Name Resolved name
+     */
+    public function getResolvedClassName(Name $name): Name {
+        return $this->getResolvedName($name, Stmt\Use_::TYPE_NORMAL);
+    }
+
+    /**
+     * Get possible ways of writing a fully qualified name (e.g., by making use of aliases).
+     *
+     * @param string $name Fully-qualified name (without leading namespace separator)
+     * @param Stmt\Use_::TYPE_* $type One of Stmt\Use_::TYPE_*
+     *
+     * @return Name[] Possible representations of the name
+     */
+    public function getPossibleNames(string $name, int $type): array {
+        $lcName = strtolower($name);
+
+        if ($type === Stmt\Use_::TYPE_NORMAL) {
+            // self, parent and static must always be unqualified
+            if ($lcName === "self" || $lcName === "parent" || $lcName === "static") {
+                return [new Name($name)];
+            }
+        }
+
+        // Collect possible ways to write this name, starting with the fully-qualified name
+        $possibleNames = [new FullyQualified($name)];
+
+        if (null !== $nsRelativeName = $this->getNamespaceRelativeName($name, $lcName, $type)) {
+            // Make sure there is no alias that makes the normally namespace-relative name
+            // into something else
+            if (null === $this->resolveAlias($nsRelativeName, $type)) {
+                $possibleNames[] = $nsRelativeName;
+            }
+        }
+
+        // Check for relevant namespace use statements
+        foreach ($this->origAliases[Stmt\Use_::TYPE_NORMAL] as $alias => $orig) {
+            $lcOrig = $orig->toLowerString();
+            if (0 === strpos($lcName, $lcOrig . '\\')) {
+                $possibleNames[] = new Name($alias . substr($name, strlen($lcOrig)));
+            }
+        }
+
+        // Check for relevant type-specific use statements
+        foreach ($this->origAliases[$type] as $alias => $orig) {
+            if ($type === Stmt\Use_::TYPE_CONSTANT) {
+                // Constants are are complicated-sensitive
+                $normalizedOrig = $this->normalizeConstName($orig->toString());
+                if ($normalizedOrig === $this->normalizeConstName($name)) {
+                    $possibleNames[] = new Name($alias);
+                }
+            } else {
+                // Everything else is case-insensitive
+                if ($orig->toLowerString() === $lcName) {
+                    $possibleNames[] = new Name($alias);
+                }
+            }
+        }
+
+        return $possibleNames;
+    }
+
+    /**
+     * Get shortest representation of this fully-qualified name.
+     *
+     * @param string $name Fully-qualified name (without leading namespace separator)
+     * @param Stmt\Use_::TYPE_* $type One of Stmt\Use_::TYPE_*
+     *
+     * @return Name Shortest representation
+     */
+    public function getShortName(string $name, int $type): Name {
+        $possibleNames = $this->getPossibleNames($name, $type);
+
+        // Find shortest name
+        $shortestName = null;
+        $shortestLength = \INF;
+        foreach ($possibleNames as $possibleName) {
+            $length = strlen($possibleName->toCodeString());
+            if ($length < $shortestLength) {
+                $shortestName = $possibleName;
+                $shortestLength = $length;
+            }
+        }
+
+        return $shortestName;
+    }
+
+    private function resolveAlias(Name $name, int $type): ?FullyQualified {
+        $firstPart = $name->getFirst();
+
+        if ($name->isQualified()) {
+            // resolve aliases for qualified names, always against class alias table
+            $checkName = strtolower($firstPart);
+            if (isset($this->aliases[Stmt\Use_::TYPE_NORMAL][$checkName])) {
+                $alias = $this->aliases[Stmt\Use_::TYPE_NORMAL][$checkName];
+                return FullyQualified::concat($alias, $name->slice(1), $name->getAttributes());
+            }
+        } elseif ($name->isUnqualified()) {
+            // constant aliases are case-sensitive, function aliases case-insensitive
+            $checkName = $type === Stmt\Use_::TYPE_CONSTANT ? $firstPart : strtolower($firstPart);
+            if (isset($this->aliases[$type][$checkName])) {
+                // resolve unqualified aliases
+                return new FullyQualified($this->aliases[$type][$checkName], $name->getAttributes());
+            }
+        }
+
+        // No applicable aliases
+        return null;
+    }
+
+    private function getNamespaceRelativeName(string $name, string $lcName, int $type): ?Name {
+        if (null === $this->namespace) {
+            return new Name($name);
+        }
+
+        if ($type === Stmt\Use_::TYPE_CONSTANT) {
+            // The constants true/false/null always resolve to the global symbols, even inside a
+            // namespace, so they may be used without qualification
+            if ($lcName === "true" || $lcName === "false" || $lcName === "null") {
+                return new Name($name);
+            }
+        }
+
+        $namespacePrefix = strtolower($this->namespace . '\\');
+        if (0 === strpos($lcName, $namespacePrefix)) {
+            return new Name(substr($name, strlen($namespacePrefix)));
+        }
+
+        return null;
+    }
+
+    private function normalizeConstName(string $name): string {
+        $nsSep = strrpos($name, '\\');
+        if (false === $nsSep) {
+            return $name;
+        }
+
+        // Constants have case-insensitive namespace and case-sensitive short-name
+        $ns = substr($name, 0, $nsSep);
+        $shortName = substr($name, $nsSep + 1);
+        return strtolower($ns) . '\\' . $shortName;
+    }
+}

lib/PhpParser/Node.php

@@ -1,77 +1,146 @@
-<?php
+<?php declare(strict_types=1);
 
 namespace PhpParser;
 
-interface Node
-{
+interface Node {
     /**
      * Gets the type of the node.
      *
      * @return string Type of the node
      */
-    public function getType();
+    public function getType(): string;
 
     /**
      * Gets the names of the sub nodes.
      *
-     * @return array Names of sub nodes
+     * @return string[] Names of sub nodes
      */
-    public function getSubNodeNames();
+    public function getSubNodeNames(): array;
+
+    /**
+     * Gets line the node started in (alias of getStartLine).
+     *
+     * @return int Start line (or -1 if not available)
+     *
+     * @deprecated Use getStartLine() instead
+     */
+    public function getLine(): int;
 
     /**
      * Gets line the node started in.
      *
-     * @return int Line
+     * Requires the 'startLine' attribute to be enabled in the lexer (enabled by default).
+     *
+     * @return int Start line (or -1 if not available)
      */
-    public function getLine();
+    public function getStartLine(): int;
 
     /**
-     * Sets line the node started in.
+     * Gets the line the node ended in.
      *
-     * @param int $line Line
+     * Requires the 'endLine' attribute to be enabled in the lexer (enabled by default).
+     *
+     * @return int End line (or -1 if not available)
      */
-    public function setLine($line);
+    public function getEndLine(): int;
+
+    /**
+     * Gets the token offset of the first token that is part of this node.
+     *
+     * The offset is an index into the array returned by Lexer::getTokens().
+     *
+     * Requires the 'startTokenPos' attribute to be enabled in the lexer (DISABLED by default).
+     *
+     * @return int Token start position (or -1 if not available)
+     */
+    public function getStartTokenPos(): int;
+
+    /**
+     * Gets the token offset of the last token that is part of this node.
+     *
+     * The offset is an index into the array returned by Lexer::getTokens().
+     *
+     * Requires the 'endTokenPos' attribute to be enabled in the lexer (DISABLED by default).
+     *
+     * @return int Token end position (or -1 if not available)
+     */
+    public function getEndTokenPos(): int;
+
+    /**
+     * Gets the file offset of the first character that is part of this node.
+     *
+     * Requires the 'startFilePos' attribute to be enabled in the lexer (DISABLED by default).
+     *
+     * @return int File start position (or -1 if not available)
+     */
+    public function getStartFilePos(): int;
+
+    /**
+     * Gets the file offset of the last character that is part of this node.
+     *
+     * Requires the 'endFilePos' attribute to be enabled in the lexer (DISABLED by default).
+     *
+     * @return int File end position (or -1 if not available)
+     */
+    public function getEndFilePos(): int;
+
+    /**
+     * Gets all comments directly preceding this node.
+     *
+     * The comments are also available through the "comments" attribute.
+     *
+     * @return Comment[]
+     */
+    public function getComments(): array;
 
     /**
      * Gets the doc comment of the node.
      *
-     * The doc comment has to be the last comment associated with the node.
-     *
      * @return null|Comment\Doc Doc comment object or null
      */
-    public function getDocComment();
+    public function getDocComment(): ?Comment\Doc;
+
+    /**
+     * Sets the doc comment of the node.
+     *
+     * This will either replace an existing doc comment or add it to the comments array.
+     *
+     * @param Comment\Doc $docComment Doc comment to set
+     */
+    public function setDocComment(Comment\Doc $docComment): void;
 
     /**
      * Sets an attribute on a node.
      *
-     * @param string $key
-     * @param mixed  $value
+     * @param mixed $value
      */
-    public function setAttribute($key, $value);
+    public function setAttribute(string $key, $value): void;
 
     /**
      * Returns whether an attribute exists.
-     *
-     * @param string $key
-     *
-     * @return bool
      */
-    public function hasAttribute($key);
+    public function hasAttribute(string $key): bool;
 
     /**
      * Returns the value of an attribute.
      *
-     * @param string $key
-     * @param mixed  $default
+     * @param mixed $default
      *
      * @return mixed
      */
-    public function &getAttribute($key, $default = null);
+    public function getAttribute(string $key, $default = null);
 
     /**
-     * Returns all attributes for the given node.
+     * Returns all the attributes of this node.
      *
-     * @return array
+     * @return array<string, mixed>
      */
-    public function getAttributes();
-}
+    public function getAttributes(): array;
+
+    /**
+     * Replaces all the attributes of this node.
+     *
+     * @param array<string, mixed> $attributes
+     */
+    public function setAttributes(array $attributes): void;
+}

lib/PhpParser/Node/Arg.php

@@ -1,34 +1,44 @@
-<?php
+<?php declare(strict_types=1);
 
 namespace PhpParser\Node;
 
 use PhpParser\NodeAbstract;
 
-class Arg extends NodeAbstract
-{
+class Arg extends NodeAbstract {
+    /** @var Identifier|null Parameter name (for named parameters) */
+    public ?Identifier $name;
     /** @var Expr Value to pass */
-    public $value;
+    public Expr $value;
     /** @var bool Whether to pass by ref */
-    public $byRef;
+    public bool $byRef;
     /** @var bool Whether to unpack the argument */
-    public $unpack;
+    public bool $unpack;
 
     /**
      * Constructs a function call argument node.
      *
-     * @param Expr  $value      Value to pass
-     * @param bool  $byRef      Whether to pass by ref
-     * @param bool  $unpack     Whether to unpack the argument
-     * @param array $attributes Additional attributes
+     * @param Expr $value Value to pass
+     * @param bool $byRef Whether to pass by ref
+     * @param bool $unpack Whether to unpack the argument
+     * @param array<string, mixed> $attributes Additional attributes
+     * @param Identifier|null $name Parameter name (for named parameters)
      */
-    public function __construct(Expr $value, $byRef = false, $unpack = false, array $attributes = array()) {
-        parent::__construct(null, $attributes);
+    public function __construct(
+        Expr $value, bool $byRef = false, bool $unpack = false, array $attributes = [],
+        ?Identifier $name = null
+    ) {
+        $this->attributes = $attributes;
+        $this->name = $name;
         $this->value = $value;
         $this->byRef = $byRef;
         $this->unpack = $unpack;
     }
 
-    public function getSubNodeNames() {
-        return array('value', 'byRef', 'unpack');
+    public function getSubNodeNames(): array {
+        return ['name', 'value', 'byRef', 'unpack'];
+    }
+
+    public function getType(): string {
+        return 'Arg';
     }
 }

lib/PhpParser/Node/ArrayItem.php

@@ -0,0 +1,43 @@
+<?php declare(strict_types=1);
+
+namespace PhpParser\Node;
+
+use PhpParser\NodeAbstract;
+
+class ArrayItem extends NodeAbstract {
+    /** @var null|Expr Key */
+    public ?Expr $key;
+    /** @var Expr Value */
+    public Expr $value;
+    /** @var bool Whether to assign by reference */
+    public bool $byRef;
+    /** @var bool Whether to unpack the argument */
+    public bool $unpack;
+
+    /**
+     * Constructs an array item node.
+     *
+     * @param Expr $value Value
+     * @param null|Expr $key Key
+     * @param bool $byRef Whether to assign by reference
+     * @param array<string, mixed> $attributes Additional attributes
+     */
+    public function __construct(Expr $value, ?Expr $key = null, bool $byRef = false, array $attributes = [], bool $unpack = false) {
+        $this->attributes = $attributes;
+        $this->key = $key;
+        $this->value = $value;
+        $this->byRef = $byRef;
+        $this->unpack = $unpack;
+    }
+
+    public function getSubNodeNames(): array {
+        return ['key', 'value', 'byRef', 'unpack'];
+    }
+
+    public function getType(): string {
+        return 'ArrayItem';
+    }
+}
+
+// @deprecated compatibility alias
+class_alias(ArrayItem::class, Expr\ArrayItem::class);

lib/PhpParser/Node/Attribute.php

@@ -0,0 +1,33 @@
+<?php declare(strict_types=1);
+
+namespace PhpParser\Node;
+
+use PhpParser\Node;
+use PhpParser\NodeAbstract;
+
+class Attribute extends NodeAbstract {
+    /** @var Name Attribute name */
+    public Name $name;
+
+    /** @var list<Arg> Attribute arguments */
+    public array $args;
+
+    /**
+     * @param Node\Name $name Attribute name
+     * @param list<Arg> $args Attribute arguments
+     * @param array<string, mixed> $attributes Additional node attributes
+     */
+    public function __construct(Name $name, array $args = [], array $attributes = []) {
+        $this->attributes = $attributes;
+        $this->name = $name;
+        $this->args = $args;
+    }
+
+    public function getSubNodeNames(): array {
+        return ['name', 'args'];
+    }
+
+    public function getType(): string {
+        return 'Attribute';
+    }
+}

lib/PhpParser/Node/AttributeGroup.php

@@ -0,0 +1,27 @@
+<?php declare(strict_types=1);
+
+namespace PhpParser\Node;
+
+use PhpParser\NodeAbstract;
+
+class AttributeGroup extends NodeAbstract {
+    /** @var Attribute[] Attributes */
+    public array $attrs;
+
+    /**
+     * @param Attribute[] $attrs PHP attributes
+     * @param array<string, mixed> $attributes Additional node attributes
+     */
+    public function __construct(array $attrs, array $attributes = []) {
+        $this->attributes = $attributes;
+        $this->attrs = $attrs;
+    }
+
+    public function getSubNodeNames(): array {
+        return ['attrs'];
+    }
+
+    public function getType(): string {
+        return 'AttributeGroup';
+    }
+}

lib/PhpParser/Node/ClosureUse.php

@@ -0,0 +1,36 @@
+<?php declare(strict_types=1);
+
+namespace PhpParser\Node;
+
+use PhpParser\NodeAbstract;
+
+class ClosureUse extends NodeAbstract {
+    /** @var Expr\Variable Variable to use */
+    public Expr\Variable $var;
+    /** @var bool Whether to use by reference */
+    public bool $byRef;
+
+    /**
+     * Constructs a closure use node.
+     *
+     * @param Expr\Variable $var Variable to use
+     * @param bool $byRef Whether to use by reference
+     * @param array<string, mixed> $attributes Additional attributes
+     */
+    public function __construct(Expr\Variable $var, bool $byRef = false, array $attributes = []) {
+        $this->attributes = $attributes;
+        $this->var = $var;
+        $this->byRef = $byRef;
+    }
+
+    public function getSubNodeNames(): array {
+        return ['var', 'byRef'];
+    }
+
+    public function getType(): string {
+        return 'ClosureUse';
+    }
+}
+
+// @deprecated compatibility alias
+class_alias(ClosureUse::class, Expr\ClosureUse::class);

lib/PhpParser/Node/ComplexType.php

@@ -0,0 +1,13 @@
+<?php declare(strict_types=1);
+
+namespace PhpParser\Node;
+
+use PhpParser\NodeAbstract;
+
+/**
+ * This is a base class for complex types, including nullable types and union types.
+ *
+ * It does not provide any shared behavior and exists only for type-checking purposes.
+ */
+abstract class ComplexType extends NodeAbstract {
+}