aleph1.co.uk Git - yaffs-website/blob - vendor/nikic/php-parser/doc/component/AST_builders.markdown

   1 AST builders
   2 ============
   3
   4 When PHP-Parser is used to generate (or modify) code by first creating an Abstract Syntax Tree and
   5 then using the [pretty printer](Pretty_printing.markdown) to convert it to PHP code, it can often
   6 be tedious to manually construct AST nodes. The project provides a number of utilities to simplify
   7 the construction of common AST nodes.
   8
   9 Fluent builders
  10 ---------------
  11
  12 The library comes with a number of builders, which allow creating node trees using a fluent
  13 interface. Builders are created using the `BuilderFactory` and the final constructed node is
  14 accessed through `getNode()`. Fluent builders are available for
  15 the following syntactic elements:
  16
  17  * namespaces and use statements
  18  * classes, interfaces and traits
  19  * methods, functions and parameters
  20  * properties
  21
  22 Here is an example:
  23
  24 ```php
  25 use PhpParser\BuilderFactory;
  26 use PhpParser\PrettyPrinter;
  27 use PhpParser\Node;
  28
  29 $factory = new BuilderFactory;
  30 $node = $factory->namespace('Name\Space')
  31     ->addStmt($factory->use('Some\Other\Thingy')->as('SomeOtherClass'))
  32     ->addStmt($factory->class('SomeOtherClass')
  33         ->extend('SomeClass')
  34         ->implement('A\Few', '\Interfaces')
  35         ->makeAbstract() // ->makeFinal()
  36
  37         ->addStmt($factory->method('someMethod')
  38             ->makePublic()
  39             ->makeAbstract() // ->makeFinal()
  40             ->setReturnType('bool')
  41             ->addParam($factory->param('someParam')->setTypeHint('SomeClass'))
  42             ->setDocComment('/**
  43                               * This method does something.
  44                               *
  45                               * @param SomeClass And takes a parameter
  46                               */')
  47         )
  48
  49         ->addStmt($factory->method('anotherMethod')
  50             ->makeProtected() // ->makePublic() [default], ->makePrivate()
  51             ->addParam($factory->param('someParam')->setDefault('test'))
  52             // it is possible to add manually created nodes
  53             ->addStmt(new Node\Expr\Print_(new Node\Expr\Variable('someParam')))
  54         )
  55
  56         // properties will be correctly reordered above the methods
  57         ->addStmt($factory->property('someProperty')->makeProtected())
  58         ->addStmt($factory->property('anotherProperty')->makePrivate()->setDefault(array(1, 2, 3)))
  59     )
  60
  61     ->getNode()
  62 ;
  63
  64 $stmts = array($node);
  65 $prettyPrinter = new PrettyPrinter\Standard();
  66 echo $prettyPrinter->prettyPrintFile($stmts);
  67 ```
  68
  69 This will produce the following output with the standard pretty printer:
  70
  71 ```php
  72 <?php
  73
  74 namespace Name\Space;
  75
  76 use Some\Other\Thingy as SomeClass;
  77 abstract class SomeOtherClass extends SomeClass implements A\Few, \Interfaces
  78 {
  79     protected $someProperty;
  80     private $anotherProperty = array(1, 2, 3);
  81     /**
  82      * This method does something.
  83      *
  84      * @param SomeClass And takes a parameter
  85      */
  86     public abstract function someMethod(SomeClass $someParam) : bool;
  87     protected function anotherMethod($someParam = 'test')
  88     {
  89         print $someParam;
  90     }
  91 }
  92 ```
  93
  94 Additional helper methods
  95 -------------------------
  96
  97 The `BuilderFactory` also provides a number of additional helper methods, which directly return
  98 nodes. The following methods are currently available:
  99
 100  * `val($value)`: Creates an AST node for a literal value like `42` or `[1, 2, 3]`.
 101  * `args(array $args)`: Creates an array of function/method arguments, including the required `Arg`
 102    wrappers. Also converts literals to AST nodes.
 103  * `funcCall($name, array $args = [])`: Create a function call node. Converts `$name` to a `Name`
 104    node and normalizes arguments.
 105  * `methodCall(Expr $var, $name, array $args = [])`: Create a method call node. Converts `$name` to
 106    an `Identifier` node and normalizes arguments.
 107  * `staticCall($class, $name, array $args = [])`: Create a static method call node. Converts
 108    `$class` to a `Name` node, `$name` to an `Identifier` node and normalizes arguments.
 109  * `new($class, array $args = [])`: Create a "new" (object creation) node. Converts `$class` to a
 110    `Name` node.
 111  * `constFetch($name)`: Create a constant fetch node. Converts `$name` to a `Name` node.
 112  * `classConstFetch($class, $name)`: Create a class constant fetch node. Converts `$class` to a
 113    `Name` node and `$name` to an `Identifier` node.
 114  * `concat(...$exprs)`: Create a tree of `BinaryOp\Concat` nodes for the given expressions.
 115
 116 These methods may be expanded on an as-needed basis. Please open an issue or PR if a common
 117 operation is missing.