1Pretty printing 2=============== 3 4Pretty printing is the process of converting a syntax tree back to PHP code. In its basic mode of 5operation the pretty printer provided by this library will print the AST using a certain predefined 6code style and will discard (nearly) all formatting of the original code. Because programmers tend 7to be rather picky about their code formatting, this mode of operation is not very suitable for 8refactoring code, but can be used for automatically generated code, which is usually only read for 9debugging purposes. 10 11Basic usage 12----------- 13 14```php 15$stmts = $parser->parse($code); 16 17// MODIFY $stmts here 18 19$prettyPrinter = new PhpParser\PrettyPrinter\Standard; 20$newCode = $prettyPrinter->prettyPrintFile($stmts); 21``` 22 23The pretty printer has three basic printing methods: `prettyPrint()`, `prettyPrintFile()` and 24`prettyPrintExpr()`. The one that is most commonly useful is `prettyPrintFile()`, which takes an 25array of statements and produces a full PHP file, including opening `<?php`. 26 27`prettyPrint()` also takes a statement array, but produces code which is valid inside an already 28open `<?php` context. Lastly, `prettyPrintExpr()` takes an `Expr` node and prints only a single 29expression. 30 31Customizing the formatting 32-------------------------- 33 34The pretty printer respects a number of `kind` attributes used by some nodes (e.g., whether an 35integer should be printed as decimal, hexadecimal, etc). Additionally, it supports three options: 36 37* `phpVersion` (defaults to 7.4) allows opting into formatting that is not supported by older PHP 38 versions. 39* `newline` (defaults to `"\n"`) can be set to `"\r\n"` in order to produce Windows newlines. 40* `indent` (defaults to four spaces `" "`) can be set to any number of spaces or a single tab. 41* `shortArraySyntax` determines the used array syntax if the `kind` attribute is not set. This is 42 a legacy option, and `phpVersion` should be used to control this behavior instead. 43 44The behaviors controlled by `phpVersion` (defaults to PHP 7.4) are: 45 46* For PHP >= 7.0, short array syntax `[]` will be used by default. This does not affect nodes that 47 specify an explicit array syntax using the `kind` attribute. 48* For PHP >= 7.0, parentheses around `yield` expressions will only be printed when necessary. 49* For PHP >= 7.1, the short array syntax `[]` will be used for destructuring by default (instead of 50 `list()`). This does not affect nodes that specify and explicit syntax using the `kind` attribute. 51* For PHP >= 7.3, a newline is no longer forced after heredoc/nowdoc strings, as the requirement 52 for this has been removed with the introduction of flexible heredoc/nowdoc strings. 53* For PHP >= 7.3, heredoc/nowdoc strings are indented just like regular code. This was allowed with 54 the introduction of flexible heredoc/nowdoc strings. 55 56The default pretty printer does not provide functionality for fine-grained customization of code 57formatting. 58 59If you want to make minor changes to the formatting, the easiest way is to extend the pretty printer 60and override the methods responsible for the node types you are interested in. 61 62If you want to have more fine-grained formatting control, the recommended method is to combine the 63default pretty printer with an existing library for code reformatting, such as 64[PHP-CS-Fixer](https://github.com/FriendsOfPHP/PHP-CS-Fixer). 65 66Formatting-preserving pretty printing 67------------------------------------- 68 69For automated code refactoring, migration and similar, you will usually only want to modify a small 70portion of the code and leave the remainder alone. The basic pretty printer is not suitable for 71this, because it will also reformat parts of the code which have not been modified. 72 73Since PHP-Parser 4.0, a formatting-preserving pretty-printing mode is available, which 74attempts to preserve the formatting of code (those AST nodes that have not changed) and only reformat 75code which has been modified or newly inserted. 76 77Use of the formatting-preservation functionality requires some additional preparatory steps: 78 79```php 80use PhpParser\{NodeTraverser, NodeVisitor, ParserFactory, PrettyPrinter}; 81 82$parser = (new ParserFactory())->createForHostVersion(); 83$oldStmts = $parser->parse($code); 84$oldTokens = $parser->getTokens(); 85 86// Run CloningVisitor before making changes to the AST. 87$traverser = new NodeTraverser(new NodeVisitor\CloningVisitor()); 88$newStmts = $traverser->traverse($oldStmts); 89 90// MODIFY $newStmts HERE 91 92$printer = new PrettyPrinter\Standard(); 93$newCode = $printer->printFormatPreserving($newStmts, $oldStmts, $oldTokens); 94``` 95 96If you make use of the name resolution functionality, you will likely want to disable the 97`replaceNodes` option. This will add resolved names as attributes, instead of directly modifying 98the AST and causing spurious changes to the pretty printed code. For more information, see the 99[name resolution documentation](Name_resolution.markdown). 100 101The formatting-preservation works on a best-effort basis and may sometimes reformat more code than 102necessary. If you encounter problems while using this functionality, please open an issue. 103