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

   1 Pretty printing
   2 ===============
   3
   4 Pretty printing is the process of converting a syntax tree back to PHP code. In its basic mode of
   5 operation the pretty printer provided by this library will print the AST using a certain predefined
   6 code style and will discard (nearly) all formatting of the original code. Because programmers tend
   7 to be rather picky about their code formatting, this mode of operation is not very suitable for
   8 refactoring code, but can be used for automatically generated code, which is usually only read for
   9 debugging purposes.
  10
  11 Basic 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
  23 The pretty printer has three basic printing methods: `prettyPrint()`, `prettyPrintFile()` and
  24 `prettyPrintExpr()`. The one that is most commonly useful is `prettyPrintFile()`, which takes an
  25 array 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
  28 open `<?php` context. Lastly, `prettyPrintExpr()` takes an `Expr` node and prints only a single
  29 expression.
  30
  31 Customizing the formatting
  32 --------------------------
  33
  34 Apart from an `shortArraySyntax` option, the default pretty printer does not provide any
  35 functionality to customize the formatting of the generated code. The pretty printer does respect a
  36 number of `kind` attributes used by some notes (e.g., whether an integer should be printed as
  37 decimal, hexadecimal, etc), but there are no options to control brace placement or similar.
  38
  39 If you want to make minor changes to the formatting, the easiest way is to extend the pretty printer
  40 and override the methods responsible for the node types you are interested in.
  41
  42 If you want to have more fine-grained formatting control, the recommended method is to combine the
  43 default pretty printer with an existing library for code reformatting, such as
  44 [PHP-CS-Fixer](https://github.com/FriendsOfPHP/PHP-CS-Fixer).
  45
  46 Formatting-preserving pretty printing
  47 -------------------------------------
  48
  49 > **Note:** This functionality is **experimental** and not yet complete.
  50
  51 For automated code refactoring, migration and similar, you will usually only want to modify a small
  52 portion of the code and leave the remainder alone. The basic pretty printer is not suitable for
  53 this, because it will also reformat parts of the code which have not been modified.
  54
  55 Since PHP-Parser 4.0, an experimental formatting-preserving pretty-printing mode is available, which
  56 attempts to preserve the formatting of code (those AST nodes that have not changed) and only reformat
  57 code which has been modified or newly inserted.
  58
  59 Use of the formatting-preservation functionality requires some additional preparatory steps:
  60
  61 ```php
  62 use PhpParser\{Lexer, NodeTraverser, NodeVisitor, Parser, PrettyPrinter};
  63
  64 $lexer = new Lexer\Emulative([
  65     'usedAttributes' => [
  66         'comments',
  67         'startLine', 'endLine',
  68         'startTokenPos', 'endTokenPos',
  69     ],
  70 ]);
  71 $parser = new Parser\Php7($lexer);
  72
  73 $traverser = new NodeTraverser();
  74 $traverser->addVisitor(new NodeVisitor\CloningVisitor());
  75
  76 $printer = new PrettyPrinter\Standard();
  77
  78 $oldStmts = $parser->parse($code);
  79 $oldTokens = $lexer->getTokens();
  80
  81 $newStmts = $traverser->traverse($oldStmts);
  82
  83 // MODIFY $newStmts HERE
  84
  85 $newCode = $printer->printFormatPreserving($newStmts, $oldStmts, $oldTokens);
  86 ```
  87
  88 If you make use of the name resolution functionality, you will likely want to disable the
  89 `replaceNodes` option. This will add resolved names as attributes, instead of directlying modifying
  90 the AST and causing spurious changes to the pretty printed code. For more information, see the
  91 [name resolution documentation](Name_resolution.markdown).
  92
  93 This functionality is experimental and not yet fully implemented. It should not provide incorrect
  94 code, but it may sometimes reformat more code than necessary. Open issues are tracked in
  95 [issue #344](https://github.com/nikic/PHP-Parser/issues/344). If you encounter problems while using
  96 this functionality, please open an issue, so we know what to prioritize.