Heimdall/vendor/nikic/php-parser/README.md

226 lines
5.9 KiB
Markdown
Raw Normal View History

2018-02-01 20:01:12 +00:00
PHP Parser
==========
2022-03-10 11:54:29 +00:00
[![Coverage Status](https://coveralls.io/repos/github/nikic/PHP-Parser/badge.svg?branch=master)](https://coveralls.io/github/nikic/PHP-Parser?branch=master)
2018-02-01 20:01:12 +00:00
2022-11-13 16:05:03 +00:00
This is a PHP 5.2 to PHP 8.2 parser written in PHP. Its purpose is to simplify static code analysis and
2018-02-01 20:01:12 +00:00
manipulation.
2022-11-13 16:05:03 +00:00
[**Documentation for version 4.x**][doc_4_x] (stable; for running on PHP >= 7.0; for parsing PHP 5.2 to PHP 8.2).
2018-02-01 20:01:12 +00:00
[Documentation for version 3.x][doc_3_x] (unsupported; for running on PHP >= 5.5; for parsing PHP 5.2 to PHP 7.2).
2018-02-01 20:01:12 +00:00
Features
--------
2018-02-01 20:01:12 +00:00
The main features provided by this library are:
2022-03-10 11:54:29 +00:00
* Parsing PHP 5, 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.
* Experimental: 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
2018-02-01 20:01:12 +00:00
Parse some PHP code into an AST and dump the result in human-readable form:
2018-02-01 20:01:12 +00:00
```php
<?php
use PhpParser\Error;
use PhpParser\NodeDumper;
use PhpParser\ParserFactory;
$code = <<<'CODE'
<?php
function test($foo)
{
var_dump($foo);
}
CODE;
$parser = (new ParserFactory)->create(ParserFactory::PREFER_PHP7);
try {
$ast = $parser->parse($code);
} catch (Error $error) {
echo "Parse error: {$error->getMessage()}\n";
return;
}
$dumper = new NodeDumper;
echo $dumper->dump($ast) . "\n";
2018-02-01 20:01:12 +00:00
```
This dumps an AST looking something like this:
2018-02-01 20:01:12 +00:00
```
2018-02-01 20:01:12 +00:00
array(
0: Stmt_Function(
byRef: false
name: Identifier(
name: test
2018-02-01 20:01:12 +00:00
)
params: array(
0: Param(
type: null
2018-02-01 20:01:12 +00:00
byRef: false
variadic: false
var: Expr_Variable(
name: foo
)
default: null
2018-02-01 20:01:12 +00:00
)
)
returnType: null
stmts: array(
0: Stmt_Expression(
expr: Expr_FuncCall(
name: Name(
parts: array(
0: var_dump
)
2018-02-01 20:01:12 +00:00
)
args: array(
0: Arg(
value: Expr_Variable(
name: foo
)
byRef: false
unpack: false
)
2018-02-01 20:01:12 +00:00
)
)
)
)
)
)
```
Let's traverse the AST and perform some kind of modification. For example, drop all function bodies:
```php
use PhpParser\Node;
use PhpParser\Node\Stmt\Function_;
use PhpParser\NodeTraverser;
use PhpParser\NodeVisitorAbstract;
$traverser = new NodeTraverser();
$traverser->addVisitor(new class extends NodeVisitorAbstract {
public function enterNode(Node $node) {
if ($node instanceof Function_) {
// Clean out the function body
$node->stmts = [];
}
}
});
$ast = $traverser->traverse($ast);
echo $dumper->dump($ast) . "\n";
```
This gives us an AST where the `Function_::$stmts` are empty:
```
array(
0: Stmt_Function(
byRef: false
name: Identifier(
name: test
)
params: array(
0: Param(
type: null
2018-02-01 20:01:12 +00:00
byRef: false
variadic: false
var: Expr_Variable(
name: foo
)
default: null
2018-02-01 20:01:12 +00:00
)
)
returnType: null
stmts: array(
)
2018-02-01 20:01:12 +00:00
)
)
```
Finally, we can convert the new AST back to PHP code:
2018-02-01 20:01:12 +00:00
```php
use PhpParser\PrettyPrinter;
2018-02-01 20:01:12 +00:00
$prettyPrinter = new PrettyPrinter\Standard;
echo $prettyPrinter->prettyPrintFile($ast);
```
2018-02-01 20:01:12 +00:00
This gives us our original code, minus the `var_dump()` call inside the function:
2018-02-01 20:01:12 +00:00
```php
<?php
function test($foo)
{
}
```
For a more comprehensive introduction, see the documentation.
2018-02-01 20:01:12 +00:00
Documentation
-------------
1. [Introduction](doc/0_Introduction.markdown)
2. [Usage of basic components](doc/2_Usage_of_basic_components.markdown)
Component documentation:
* [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)
* Lexer options
* Token and file positions for nodes
* Custom 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)
2022-03-10 11:54:29 +00:00
* Disabling Xdebug
* Reusing objects
* Garbage collection impact
* [Frequently asked questions](doc/component/FAQ.markdown)
* Parent and sibling references
[doc_3_x]: https://github.com/nikic/PHP-Parser/tree/3.x/doc
2022-11-13 16:05:03 +00:00
[doc_4_x]: https://github.com/nikic/PHP-Parser/tree/4.x/doc