Chris@13: AST builders
Chris@13: ============
Chris@13: 
Chris@13: When PHP-Parser is used to generate (or modify) code by first creating an Abstract Syntax Tree and
Chris@13: then using the [pretty printer](Pretty_printing.markdown) to convert it to PHP code, it can often
Chris@13: be tedious to manually construct AST nodes. The project provides a number of utilities to simplify
Chris@13: the construction of common AST nodes.
Chris@13: 
Chris@13: Fluent builders
Chris@13: ---------------
Chris@13: 
Chris@13: The library comes with a number of builders, which allow creating node trees using a fluent
Chris@13: interface. Builders are created using the `BuilderFactory` and the final constructed node is
Chris@13: accessed through `getNode()`. Fluent builders are available for
Chris@13: the following syntactic elements:
Chris@13: 
Chris@13:  * namespaces and use statements
Chris@13:  * classes, interfaces and traits
Chris@13:  * methods, functions and parameters
Chris@13:  * properties
Chris@13: 
Chris@13: Here is an example:
Chris@13: 
Chris@13: ```php
Chris@13: use PhpParser\BuilderFactory;
Chris@13: use PhpParser\PrettyPrinter;
Chris@13: use PhpParser\Node;
Chris@13: 
Chris@13: $factory = new BuilderFactory;
Chris@13: $node = $factory->namespace('Name\Space')
Chris@17:     ->addStmt($factory->use('Some\Other\Thingy')->as('SomeClass'))
Chris@17:     ->addStmt($factory->useFunction('strlen'))
Chris@17:     ->addStmt($factory->useConst('PHP_VERSION'))
Chris@13:     ->addStmt($factory->class('SomeOtherClass')
Chris@13:         ->extend('SomeClass')
Chris@13:         ->implement('A\Few', '\Interfaces')
Chris@13:         ->makeAbstract() // ->makeFinal()
Chris@13: 
Chris@17:         ->addStmt($factory->useTrait('FirstTrait'))
Chris@17: 
Chris@17:         ->addStmt($factory->useTrait('SecondTrait', 'ThirdTrait')
Chris@17:             ->and('AnotherTrait')
Chris@17:             ->with($factory->traitUseAdaptation('foo')->as('bar'))
Chris@17:             ->with($factory->traitUseAdaptation('AnotherTrait', 'baz')->as('test'))
Chris@17:             ->with($factory->traitUseAdaptation('AnotherTrait', 'func')->insteadof('SecondTrait')))
Chris@17: 
Chris@13:         ->addStmt($factory->method('someMethod')
Chris@13:             ->makePublic()
Chris@13:             ->makeAbstract() // ->makeFinal()
Chris@17:             ->setReturnType('bool') // ->makeReturnByRef()
Chris@17:             ->addParam($factory->param('someParam')->setType('SomeClass'))
Chris@13:             ->setDocComment('/**
Chris@13:                               * This method does something.
Chris@13:                               *
Chris@13:                               * @param SomeClass And takes a parameter
Chris@13:                               */')
Chris@13:         )
Chris@13: 
Chris@13:         ->addStmt($factory->method('anotherMethod')
Chris@13:             ->makeProtected() // ->makePublic() [default], ->makePrivate()
Chris@13:             ->addParam($factory->param('someParam')->setDefault('test'))
Chris@13:             // it is possible to add manually created nodes
Chris@13:             ->addStmt(new Node\Expr\Print_(new Node\Expr\Variable('someParam')))
Chris@13:         )
Chris@13: 
Chris@13:         // properties will be correctly reordered above the methods
Chris@13:         ->addStmt($factory->property('someProperty')->makeProtected())
Chris@13:         ->addStmt($factory->property('anotherProperty')->makePrivate()->setDefault(array(1, 2, 3)))
Chris@13:     )
Chris@13: 
Chris@13:     ->getNode()
Chris@13: ;
Chris@13: 
Chris@13: $stmts = array($node);
Chris@13: $prettyPrinter = new PrettyPrinter\Standard();
Chris@13: echo $prettyPrinter->prettyPrintFile($stmts);
Chris@13: ```
Chris@13: 
Chris@13: This will produce the following output with the standard pretty printer:
Chris@13: 
Chris@13: ```php
Chris@13: <?php
Chris@13: 
Chris@13: namespace Name\Space;
Chris@13: 
Chris@13: use Some\Other\Thingy as SomeClass;
Chris@17: use function strlen;
Chris@17: use const PHP_VERSION;
Chris@13: abstract class SomeOtherClass extends SomeClass implements A\Few, \Interfaces
Chris@13: {
Chris@17:     use FirstTrait;
Chris@17:     use SecondTrait, ThirdTrait, AnotherTrait {
Chris@17:         foo as bar;
Chris@17:         AnotherTrait::baz as test;
Chris@17:         AnotherTrait::func insteadof SecondTrait;
Chris@17:     }
Chris@13:     protected $someProperty;
Chris@13:     private $anotherProperty = array(1, 2, 3);
Chris@13:     /**
Chris@13:      * This method does something.
Chris@13:      *
Chris@13:      * @param SomeClass And takes a parameter
Chris@13:      */
Chris@13:     public abstract function someMethod(SomeClass $someParam) : bool;
Chris@13:     protected function anotherMethod($someParam = 'test')
Chris@13:     {
Chris@13:         print $someParam;
Chris@13:     }
Chris@13: }
Chris@13: ```
Chris@13: 
Chris@13: Additional helper methods
Chris@13: -------------------------
Chris@13: 
Chris@13: The `BuilderFactory` also provides a number of additional helper methods, which directly return
Chris@13: nodes. The following methods are currently available:
Chris@13: 
Chris@13:  * `val($value)`: Creates an AST node for a literal value like `42` or `[1, 2, 3]`.
Chris@17:  * `var($name)`: Creates variable node.
Chris@13:  * `args(array $args)`: Creates an array of function/method arguments, including the required `Arg`
Chris@13:    wrappers. Also converts literals to AST nodes.
Chris@13:  * `funcCall($name, array $args = [])`: Create a function call node. Converts `$name` to a `Name`
Chris@13:    node and normalizes arguments.
Chris@13:  * `methodCall(Expr $var, $name, array $args = [])`: Create a method call node. Converts `$name` to
Chris@13:    an `Identifier` node and normalizes arguments.
Chris@13:  * `staticCall($class, $name, array $args = [])`: Create a static method call node. Converts
Chris@13:    `$class` to a `Name` node, `$name` to an `Identifier` node and normalizes arguments.
Chris@13:  * `new($class, array $args = [])`: Create a "new" (object creation) node. Converts `$class` to a
Chris@13:    `Name` node.
Chris@13:  * `constFetch($name)`: Create a constant fetch node. Converts `$name` to a `Name` node.
Chris@13:  * `classConstFetch($class, $name)`: Create a class constant fetch node. Converts `$class` to a
Chris@13:    `Name` node and `$name` to an `Identifier` node.
Chris@17:  * `propertyFetch($var, $name)`: Creates a property fetch node. Converts `$name` to an `Identifier`
Chris@17:    node.
Chris@13:  * `concat(...$exprs)`: Create a tree of `BinaryOp\Concat` nodes for the given expressions.
Chris@13: 
Chris@13: These methods may be expanded on an as-needed basis. Please open an issue or PR if a common
Chris@17: operation is missing.