www.aleph1.co.uk Git - yaffs-website/blob - vendor/nikic/php-parser/UPGRADE-2.0.md

   1 Upgrading from PHP-Parser 1.x to 2.0
   2 ====================================
   3
   4 ### PHP version requirements
   5
   6 PHP-Parser now requires PHP 5.4 or newer to run. It is however still possible to *parse* PHP 5.2 and
   7 PHP 5.3 source code, while running on a newer version.
   8
   9 ### Creating a parser instance
  10
  11 Parser instances should now be created through the `ParserFactory`. Old direct instantiation code
  12 will not work, because the parser class was renamed.
  13
  14 Old:
  15
  16 ```php
  17 use PhpParser\Parser, PhpParser\Lexer;
  18 $parser = new Parser(new Lexer\Emulative);
  19 ```
  20
  21 New:
  22
  23 ```php
  24 use PhpParser\ParserFactory;
  25 $parser = (new ParserFactory)->create(ParserFactory::PREFER_PHP7);
  26 ```
  27
  28 The first argument to `ParserFactory` determines how different PHP versions are handled. The
  29 possible values are:
  30
  31  * `ParserFactory::PREFER_PHP7`: Try to parse code as PHP 7. If this fails, try to parse it as PHP 5.
  32  * `ParserFactory::PREFER_PHP5`: Try to parse code as PHP 5. If this fails, try to parse it as PHP 7.
  33  * `ParserFactory::ONLY_PHP7`: Parse code as PHP 7.
  34  * `ParserFactory::ONLY_PHP5`: Parse code as PHP 5.
  35
  36 For most practical purposes the difference between `PREFER_PHP7` and `PREFER_PHP5` is mainly whether
  37 a scalar type hint like `string` will be stored as `'string'` (PHP 7) or as `new Name('string')`
  38 (PHP 5).
  39
  40 To use a custom lexer, pass it as the second argument to the `create()` method:
  41
  42 ```php
  43 use PhpParser\ParserFactory;
  44 $lexer = new MyLexer;
  45 $parser = (new ParserFactory)->create(ParserFactory::PREFER_PHP7, $lexer);
  46 ```
  47
  48 ### Rename of the `PhpParser\Parser` class
  49
  50 `PhpParser\Parser` is now an interface, which is implemented by `Parser\Php5`, `Parser\Php7` and
  51 `Parser\Multiple`. Parser tokens are now defined in `Parser\Tokens`. If you use the `ParserFactory`
  52 described above to create your parser instance, these changes should have no further impact on you.
  53
  54 ### Removal of legacy aliases
  55
  56 All legacy aliases for classes have been removed. This includes the old non-namespaced `PHPParser_`
  57 classes, as well as the classes that had to be renamed for PHP 7 support.
  58
  59 ### Deprecations
  60
  61 The `set()`, `setFirst()`, `append()` and `prepend()` methods of the `Node\Name` class have been
  62 deprecated. Instead `Name::concat()` and `Name->slice()` should be used.
  63
  64 ### Miscellaneous
  65
  66 * The `NodeTraverser` no longer clones nodes by default. If you want to restore the old behavior,
  67   pass `true` to the constructor.
  68 * The legacy node format has been removed. If you use custom nodes, they are now expected to
  69   implement a `getSubNodeNames()` method.
  70 * The default value for `Scalar` node constructors was removed. This means that something like
  71   `new LNumber()` should be replaced by `new LNumber(0)`.
  72 * String parts of encapsed strings are now represented using `Scalar\EncapsStringPart` nodes, while
  73   previously raw strings were used. This affects the `parts` child of `Scalar\Encaps` and
  74   `Expr\ShellExec`.