Chris@0: Other node tree representations
Chris@0: ===============================
Chris@0: 
Chris@0: It is possible to convert the AST into several textual representations, which serve different uses.
Chris@0: 
Chris@0: Simple serialization
Chris@0: --------------------
Chris@0: 
Chris@0: It is possible to serialize the node tree using `serialize()` and also unserialize it using
Chris@0: `unserialize()`. The output is not human readable and not easily processable from anything
Chris@0: but PHP, but it is compact and generates quickly. The main application thus is in caching.
Chris@0: 
Chris@0: Human readable dumping
Chris@0: ----------------------
Chris@0: 
Chris@0: Furthermore it is possible to dump nodes into a human readable format using the `dump` method of
Chris@0: `PhpParser\NodeDumper`. This can be used for debugging.
Chris@0: 
Chris@0: ```php
Chris@0: $code = <<<'CODE'
Chris@0: <?php
Chris@0: 
Chris@0: function printLine($msg) {
Chris@0:     echo $msg, "\n";
Chris@0: }
Chris@0: 
Chris@0: printLine('Hello World!!!');
Chris@0: CODE;
Chris@0: 
Chris@0: $parser = (new PhpParser\ParserFactory)->create(PhpParser\ParserFactory::PREFER_PHP7);
Chris@0: $nodeDumper = new PhpParser\NodeDumper;
Chris@0: 
Chris@0: try {
Chris@0:     $stmts = $parser->parse($code);
Chris@0: 
Chris@0:     echo $nodeDumper->dump($stmts), "\n";
Chris@0: } catch (PhpParser\Error $e) {
Chris@0:     echo 'Parse Error: ', $e->getMessage();
Chris@0: }
Chris@0: ```
Chris@0: 
Chris@0: The above script will have an output looking roughly like this:
Chris@0: 
Chris@0: ```
Chris@0: array(
Chris@0:     0: Stmt_Function(
Chris@0:         byRef: false
Chris@0:         params: array(
Chris@0:             0: Param(
Chris@0:                 name: msg
Chris@0:                 default: null
Chris@0:                 type: null
Chris@0:                 byRef: false
Chris@0:             )
Chris@0:         )
Chris@0:         stmts: array(
Chris@0:             0: Stmt_Echo(
Chris@0:                 exprs: array(
Chris@0:                     0: Expr_Variable(
Chris@0:                         name: msg
Chris@0:                     )
Chris@0:                     1: Scalar_String(
Chris@0:                         value:
Chris@0: 
Chris@0:                     )
Chris@0:                 )
Chris@0:             )
Chris@0:         )
Chris@0:         name: printLine
Chris@0:     )
Chris@0:     1: Expr_FuncCall(
Chris@0:         name: Name(
Chris@0:             parts: array(
Chris@0:                 0: printLine
Chris@0:             )
Chris@0:         )
Chris@0:         args: array(
Chris@0:             0: Arg(
Chris@0:                 value: Scalar_String(
Chris@0:                     value: Hello World!!!
Chris@0:                 )
Chris@0:                 byRef: false
Chris@0:             )
Chris@0:         )
Chris@0:     )
Chris@0: )
Chris@0: ```
Chris@0: 
Chris@0: JSON encoding
Chris@0: -------------
Chris@0: 
Chris@0: Nodes (and comments) implement the `JsonSerializable` interface. As such, it is possible to JSON
Chris@0: encode the AST directly using `json_encode()`:
Chris@0: 
Chris@0: ```php
Chris@0: $code = <<<'CODE'
Chris@0: <?php
Chris@0: 
Chris@0: function printLine($msg) {
Chris@0:     echo $msg, "\n";
Chris@0: }
Chris@0: 
Chris@0: printLine('Hello World!!!');
Chris@0: CODE;
Chris@0: 
Chris@0: $parser = (new PhpParser\ParserFactory)->create(PhpParser\ParserFactory::PREFER_PHP7);
Chris@0: $nodeDumper = new PhpParser\NodeDumper;
Chris@0: 
Chris@0: try {
Chris@0:     $stmts = $parser->parse($code);
Chris@0: 
Chris@0:     echo json_encode($stmts, JSON_PRETTY_PRINT), "\n";
Chris@0: } catch (PhpParser\Error $e) {
Chris@0:     echo 'Parse Error: ', $e->getMessage();
Chris@0: }
Chris@0: ```
Chris@0: 
Chris@0: This will result in the following output (which includes attributes):
Chris@0: 
Chris@0: ```json
Chris@0: [
Chris@0:     {
Chris@0:         "nodeType": "Stmt_Function",
Chris@0:         "byRef": false,
Chris@0:         "name": "printLine",
Chris@0:         "params": [
Chris@0:             {
Chris@0:                 "nodeType": "Param",
Chris@0:                 "type": null,
Chris@0:                 "byRef": false,
Chris@0:                 "variadic": false,
Chris@0:                 "name": "msg",
Chris@0:                 "default": null,
Chris@0:                 "attributes": {
Chris@0:                     "startLine": 3,
Chris@0:                     "endLine": 3
Chris@0:                 }
Chris@0:             }
Chris@0:         ],
Chris@0:         "returnType": null,
Chris@0:         "stmts": [
Chris@0:             {
Chris@0:                 "nodeType": "Stmt_Echo",
Chris@0:                 "exprs": [
Chris@0:                     {
Chris@0:                         "nodeType": "Expr_Variable",
Chris@0:                         "name": "msg",
Chris@0:                         "attributes": {
Chris@0:                             "startLine": 4,
Chris@0:                             "endLine": 4
Chris@0:                         }
Chris@0:                     },
Chris@0:                     {
Chris@0:                         "nodeType": "Scalar_String",
Chris@0:                         "value": "\n",
Chris@0:                         "attributes": {
Chris@0:                             "startLine": 4,
Chris@0:                             "endLine": 4,
Chris@0:                             "kind": 2
Chris@0:                         }
Chris@0:                     }
Chris@0:                 ],
Chris@0:                 "attributes": {
Chris@0:                     "startLine": 4,
Chris@0:                     "endLine": 4
Chris@0:                 }
Chris@0:             }
Chris@0:         ],
Chris@0:         "attributes": {
Chris@0:             "startLine": 3,
Chris@0:             "endLine": 5
Chris@0:         }
Chris@0:     },
Chris@0:     {
Chris@0:         "nodeType": "Expr_FuncCall",
Chris@0:         "name": {
Chris@0:             "nodeType": "Name",
Chris@0:             "parts": [
Chris@0:                 "printLine"
Chris@0:             ],
Chris@0:             "attributes": {
Chris@0:                 "startLine": 7,
Chris@0:                 "endLine": 7
Chris@0:             }
Chris@0:         },
Chris@0:         "args": [
Chris@0:             {
Chris@0:                 "nodeType": "Arg",
Chris@0:                 "value": {
Chris@0:                     "nodeType": "Scalar_String",
Chris@0:                     "value": "Hello World!!!",
Chris@0:                     "attributes": {
Chris@0:                         "startLine": 7,
Chris@0:                         "endLine": 7,
Chris@0:                         "kind": 1
Chris@0:                     }
Chris@0:                 },
Chris@0:                 "byRef": false,
Chris@0:                 "unpack": false,
Chris@0:                 "attributes": {
Chris@0:                     "startLine": 7,
Chris@0:                     "endLine": 7
Chris@0:                 }
Chris@0:             }
Chris@0:         ],
Chris@0:         "attributes": {
Chris@0:             "startLine": 7,
Chris@0:             "endLine": 7
Chris@0:         }
Chris@0:     }
Chris@0: ]
Chris@0: ```
Chris@0: 
Chris@0: There is currently no mechanism to convert JSON back into a node tree. Furthermore, not all ASTs
Chris@0: can be JSON encoded. In particular, JSON only supports UTF-8 strings.
Chris@0: 
Chris@0: Serialization to XML
Chris@0: --------------------
Chris@0: 
Chris@0: It is also possible to serialize the node tree to XML using `PhpParser\Serializer\XML->serialize()`
Chris@0: and to unserialize it using `PhpParser\Unserializer\XML->unserialize()`. This is useful for
Chris@0: interfacing with other languages and applications or for doing transformation using XSLT.
Chris@0: 
Chris@0: ```php
Chris@0: <?php
Chris@0: $code = <<<'CODE'
Chris@0: <?php
Chris@0: 
Chris@0: function printLine($msg) {
Chris@0:     echo $msg, "\n";
Chris@0: }
Chris@0: 
Chris@0: printLine('Hello World!!!');
Chris@0: CODE;
Chris@0: 
Chris@0: $parser = (new PhpParser\ParserFactory)->create(PhpParser\ParserFactory::PREFER_PHP7);
Chris@0: $serializer = new PhpParser\Serializer\XML;
Chris@0: 
Chris@0: try {
Chris@0:     $stmts = $parser->parse($code);
Chris@0: 
Chris@0:     echo $serializer->serialize($stmts);
Chris@0: } catch (PhpParser\Error $e) {
Chris@0:     echo 'Parse Error: ', $e->getMessage();
Chris@0: }
Chris@0: ```
Chris@0: 
Chris@0: Produces:
Chris@0: 
Chris@0: ```xml
Chris@0: <?xml version="1.0" encoding="UTF-8"?>
Chris@0: <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">
Chris@0:  <scalar:array>
Chris@0:   <node:Stmt_Function line="2">
Chris@0:    <subNode:byRef>
Chris@0:     <scalar:false/>
Chris@0:    </subNode:byRef>
Chris@0:    <subNode:params>
Chris@0:     <scalar:array>
Chris@0:      <node:Param line="2">
Chris@0:       <subNode:name>
Chris@0:        <scalar:string>msg</scalar:string>
Chris@0:       </subNode:name>
Chris@0:       <subNode:default>
Chris@0:        <scalar:null/>
Chris@0:       </subNode:default>
Chris@0:       <subNode:type>
Chris@0:        <scalar:null/>
Chris@0:       </subNode:type>
Chris@0:       <subNode:byRef>
Chris@0:        <scalar:false/>
Chris@0:       </subNode:byRef>
Chris@0:      </node:Param>
Chris@0:     </scalar:array>
Chris@0:    </subNode:params>
Chris@0:    <subNode:stmts>
Chris@0:     <scalar:array>
Chris@0:      <node:Stmt_Echo line="3">
Chris@0:       <subNode:exprs>
Chris@0:        <scalar:array>
Chris@0:         <node:Expr_Variable line="3">
Chris@0:          <subNode:name>
Chris@0:           <scalar:string>msg</scalar:string>
Chris@0:          </subNode:name>
Chris@0:         </node:Expr_Variable>
Chris@0:         <node:Scalar_String line="3">
Chris@0:          <subNode:value>
Chris@0:           <scalar:string>
Chris@0: </scalar:string>
Chris@0:          </subNode:value>
Chris@0:         </node:Scalar_String>
Chris@0:        </scalar:array>
Chris@0:       </subNode:exprs>
Chris@0:      </node:Stmt_Echo>
Chris@0:     </scalar:array>
Chris@0:    </subNode:stmts>
Chris@0:    <subNode:name>
Chris@0:     <scalar:string>printLine</scalar:string>
Chris@0:    </subNode:name>
Chris@0:   </node:Stmt_Function>
Chris@0:   <node:Expr_FuncCall line="6">
Chris@0:    <subNode:name>
Chris@0:     <node:Name line="6">
Chris@0:      <subNode:parts>
Chris@0:       <scalar:array>
Chris@0:        <scalar:string>printLine</scalar:string>
Chris@0:       </scalar:array>
Chris@0:      </subNode:parts>
Chris@0:     </node:Name>
Chris@0:    </subNode:name>
Chris@0:    <subNode:args>
Chris@0:     <scalar:array>
Chris@0:      <node:Arg line="6">
Chris@0:       <subNode:value>
Chris@0:        <node:Scalar_String line="6">
Chris@0:         <subNode:value>
Chris@0:          <scalar:string>Hello World!!!</scalar:string>
Chris@0:         </subNode:value>
Chris@0:        </node:Scalar_String>
Chris@0:       </subNode:value>
Chris@0:       <subNode:byRef>
Chris@0:        <scalar:false/>
Chris@0:       </subNode:byRef>
Chris@0:      </node:Arg>
Chris@0:     </scalar:array>
Chris@0:    </subNode:args>
Chris@0:   </node:Expr_FuncCall>
Chris@0:  </scalar:array>
Chris@0: </AST>
Chris@0: ```