php-parser/README.md

184 lines
4.4 KiB
Markdown
Raw Normal View History

2018-01-02 12:41:54 +00:00
<!--
Title: PHP Parser
Description: A Parser for PHP written in Go.
2018-05-16 11:02:28 +00:00
Author: Slizov Vadym
Keywords: php parser go golang ast
2018-01-02 12:41:54 +00:00
-->
2018-05-16 11:02:28 +00:00
PHP Parser written in Go
========================
2018-04-10 20:45:26 +00:00
<img src="./parser.jpg" alt="PHP Parser written in Go" width="980"/>
2018-01-09 16:36:06 +00:00
2018-01-10 22:32:20 +00:00
[![Go Report Card](https://goreportcard.com/badge/github.com/z7zmey/php-parser)](https://goreportcard.com/report/github.com/z7zmey/php-parser)
2018-01-09 16:36:06 +00:00
[![Exago](https://api.exago.io:443/badge/tests/github.com/z7zmey/php-parser)](https://exago.io/project/github.com/z7zmey/php-parser)
2018-01-12 07:44:56 +00:00
[![Exago](https://api.exago.io:443/badge/cov/github.com/z7zmey/php-parser)](https://exago.io/project/github.com/z7zmey/php-parser)
2018-02-19 12:34:49 +00:00
[![GoDoc](https://godoc.org/github.com/z7zmey/php-parser?status.svg)](https://godoc.org/github.com/z7zmey/php-parser)
2018-01-09 16:36:06 +00:00
2018-06-07 16:52:44 +00:00
This project uses [goyacc](https://godoc.org/golang.org/x/tools/cmd/goyacc) and [golex](https://github.com/cznic/golex) libraries to parse PHP sources into [AST](https://en.wikipedia.org/wiki/Abstract_syntax_tree). It can be used to write static analysis, refactoring, metrics, code style formatting tools.
2018-03-04 13:47:41 +00:00
#### Try it online: [demo](https://php-parser.com)
2018-05-16 11:02:28 +00:00
Features:
---------
2018-04-10 20:45:26 +00:00
- Fully support PHP 5 and PHP 7 syntax
- Abstract syntax tree (AST) representation
2018-01-09 16:36:06 +00:00
- Traversing AST
2018-02-27 21:59:27 +00:00
- Namespace resolver
2018-04-10 20:45:26 +00:00
- Able to parse syntax-invalid PHP files
2018-05-16 11:02:28 +00:00
Roadmap
-------
2018-04-10 20:45:26 +00:00
2018-06-07 16:52:44 +00:00
- Pretty printer
2018-04-10 20:45:26 +00:00
- Control Flow Graph (CFG)
- PhpDocComment parser
- Stabilize api
2018-01-09 16:29:05 +00:00
2018-05-16 11:02:28 +00:00
Install
-------
2018-02-06 10:52:31 +00:00
```
go get github.com/z7zmey/php-parser
```
2018-05-16 11:02:28 +00:00
CLI
---
2018-04-10 20:45:26 +00:00
```
2018-06-19 20:55:12 +00:00
php-parser [flags] <path> ...
2018-04-10 20:45:26 +00:00
```
2018-06-19 20:55:12 +00:00
| flag | type | description |
|-------|------|----------------------------------------------|
| -d |string| dump format: [custom, go, json, pretty-json] |
2018-06-21 17:37:34 +00:00
| -prof |string| start profiler: [cpu, mem] |
2018-06-19 20:55:12 +00:00
| -p | bool | show positions |
| -c | bool | show comments |
| -r | bool | resolve names |
| -php5 | bool | parse as PHP5 |
2018-04-10 20:45:26 +00:00
Dump AST to stdout.
2018-05-16 11:02:28 +00:00
Example
-------
2018-01-12 08:04:31 +00:00
```Golang
package main
import (
2018-04-10 12:51:00 +00:00
"fmt"
2018-01-12 08:04:31 +00:00
"bytes"
"os"
2018-01-12 08:04:31 +00:00
2018-02-04 19:49:53 +00:00
"github.com/z7zmey/php-parser/php7"
2018-01-12 08:04:31 +00:00
"github.com/z7zmey/php-parser/visitor"
)
func main() {
2018-01-12 08:17:41 +00:00
src := bytes.NewBufferString(`<? echo "Hello world";`)
2018-04-09 20:30:44 +00:00
2018-04-10 12:51:00 +00:00
parser := php7.NewParser(src, "example.php")
parser.Parse()
for _, e := range parser.GetErrors() {
fmt.Println(e)
}
2018-01-12 08:04:31 +00:00
2018-02-04 19:35:46 +00:00
visitor := visitor.Dumper{
2018-04-09 20:30:44 +00:00
Writer: os.Stdout,
2018-02-04 19:35:46 +00:00
Indent: "",
2018-04-10 12:51:00 +00:00
Comments: parser.GetComments(),
Positions: parser.GetPositions(),
2018-02-04 19:35:46 +00:00
}
2018-04-10 12:51:00 +00:00
rootNode := parser.GetRootNode()
rootNode.Walk(visitor)
2018-01-12 08:04:31 +00:00
}
```
2018-05-16 11:02:28 +00:00
Namespace resolver
------------------
2018-02-06 10:52:31 +00:00
2018-04-10 20:45:26 +00:00
Namespace resolver is a visitor that resolves nodes fully qualified name and saves into `map[node.Node]string` structure
2018-02-06 10:52:31 +00:00
2018-04-10 20:45:26 +00:00
- For `Class`, `Interface`, `Trait`, `Function`, `Constant` nodes it saves name with current namespace.
- For `Name`, `Relative`, `FullyQualified` nodes it resolves `use` aliases and saves a fully qualified name.
2018-03-01 21:14:51 +00:00
2018-05-16 11:02:28 +00:00
Parsing syntax-invalid PHP files
--------------------------------
2018-03-01 21:14:51 +00:00
2018-04-10 20:45:26 +00:00
If we try to parse `$a$b;` then the parser triggers error 'syntax error: unexpected T_VARIABLE'. Token `$b` is unexpected, but parser recovers parsing process and returns `$b;` statement to AST, because it is syntactically correct.
2018-03-01 21:14:51 +00:00
2018-06-07 16:52:44 +00:00
Pretty printer [work in progress]
---------------------------------
2018-04-06 12:23:33 +00:00
```Golang
nodes := &stmt.StmtList{
Stmts: []node.Node{
&stmt.Namespace{
2018-05-16 11:02:28 +00:00
NamespaceName: &name.Name{
Parts: []node.Node{
&name.NamePart{Value: "Foo"},
},
},
2018-04-06 12:23:33 +00:00
},
&stmt.Class{
2018-05-16 11:02:28 +00:00
Modifiers: []node.Node{
&node.Identifier{Value: "abstract"},
},
ClassName: &name.Name{
Parts: []node.Node{
&name.NamePart{Value: "Bar"},
},
},
Extends: &stmt.ClassExtends{
2018-06-07 16:52:44 +00:00
ClassName: &name.Name{
Parts: []node.Node{
&name.NamePart{
Value: "Baz"
},
},
},
},
2018-04-06 12:23:33 +00:00
Stmts: []node.Node{
&stmt.ClassMethod{
2018-05-16 11:02:28 +00:00
Modifiers: []node.Node{
&node.Identifier{Value: "public"},
},
2018-04-06 12:23:33 +00:00
MethodName: &node.Identifier{Value: "greet"},
2018-06-03 06:35:44 +00:00
Stmt: &stmt.StmtList{
Stmts: []node.Node{
&stmt.Echo{
Exprs: []node.Node{
&scalar.String{Value: "'Hello world'"},
},
2018-04-06 12:23:33 +00:00
},
},
},
},
},
},
},
}
file := os.Stdout
p := printer.NewPrinter(file, " ")
2018-06-18 02:16:05 +00:00
p.Print(nodes)
2018-04-06 12:23:33 +00:00
```
2018-05-16 11:02:28 +00:00
It prints to stdout:
2018-04-06 12:23:33 +00:00
```PHP
<?php
namespace Foo;
abstract class Bar extends Baz
{
2018-06-07 16:52:44 +00:00
public function greet()
{
echo 'Hello world';
}
2018-04-06 12:23:33 +00:00
}
```