PHP-Parser 5.0.0

See the upgrading guide for detailed migration instructions. The changelog is relative to PHP-Parser 4.18.0.

Added

• Added PhpVersion class, which is accepted in a number of places (e.g. ParserFactory, Parser, Lexer, PrettyPrinter) and gives more precise control over the PHP version being targeted.
• Added PHP 8 parser though it only differs from the PHP 7 parser in concatenation precedence.
• Added Parser::getTokens() method.
• Added a Modifiers class, as a replacement for Stmt\Class_::MODIFIER_*.
• Added support for returning an array or REMOVE_NODE from NodeVisitor::enterNode().
• Added many additional type annotations. PhpStan is now used.
• Added a fuzzing target for PHP-Fuzzer, which was how a lot of pretty printer bugs were found.
• Added isPromoted(), isPublic(), isProtected(), isPrivate() and isReadonly() methods on Param.
• Added support for class constants in trait builder.
• Added PrettyPrinter interface.
• Added support for formatting preservation when toggling static modifiers.
• The php-parse binary now accepts - as the file name, in which case it will read from stdin.
• Added support for NodeVisitor::REPLACE_WITH_NULL.
• Added support for CRLF newlines in the pretty printer, using the new newline option.
• Visitors can now be passed directly to the NodeTraverser constructor. A separate call to addVisitor() is no longer required.
• Added support for printing additional attributes (like kind) in NodeDumper.
• Added rawValue attribute to InterpolatedStringPart and heredoc/nowdoc String_s, which provides the original, unparsed value. It was previously only available for non-interpolated single/double quoted strings.
• Added Stmt\Block to represent {} code blocks. Previously, such code blocks were flattened into the parent statements array. Stmt\Block will not be created for structures that are typically used with code blocks, for example if ($x) { $y; } will be represented as previously, while if ($x) { { $x; } } will have an extra Stmt\Block wrapper.

Changed

• PHP 7.4 is now required to run PHP-Parser.
• Property types have been added where possible.
• Formatting of the standard pretty printer has been adjusted to match PSR-12 more closely.
• The internal token representation now uses a PhpParser\Token class, which is compatible with PHP 8 token representation (PhpToken).
• Array destructuring is now always represented using Expr\List_ nodes, even if it uses [] syntax.
• Renamed a number of node classes, and moved things that were not real expressions/statements outside the Expr/Stmt hierarchy. Compatibility shims for the old names have been retained.
• The pretty printer no longer unconditionally wraps yield in parentheses, unless the target version is set to older than PHP 7.0.
• The pretty printer now defaults to PHP 7.4 as the target version.
• Print else if { } instead of else { if { } }.
• The leaveNode() method on visitors is now invoked in reverse order of enterNode().
• Moved NodeTraverser::REMOVE_NODE etc. to NodeVisitor::REMOVE_NODE. The old constants are still available for compatibility.
• The Name subnode parts has been replaced by name, which stores the name as a string rather than an array of parts separated by namespace separators. The getParts() method returns the old representation.
• No longer accept strings for types in Node constructors. Instead, either an Identifier, Name or ComplexType must be passed.
• Comment::getReformattedText() now normalizes CRLF newlines to LF newlines.
• The Lexer no longer accepts options. Lexer\Emulative only accepts a PhpVersion. The startLexing(), getTokens() and handleHaltCompiler() methods have been removed. Instead, there is a single method tokenize() returning the tokens.
• Attribute handling has been moved from the lexer to the parser, and is no longer configurable. The comments, startLine, endLine, startTokenPos, endTokenPos, startFilePos, and endFilePos attributes will always be added.
• The pretty printer now indents heredoc/nowdoc strings if the target version is >= 7.3 (flexible heredoc/nowdoc).
• Use visitor to assign comments. This fixes the long-standing issue where comments were assigned to all nodes sharing a starting position. Now only the outer-most node will hold the comments.
• Improve NodeDumper performance for large dumps.

Removed

• The PHP 5 parser has been removed. The PHP 7 parser has been adjusted to deal with PHP 5 code more gracefully.
• Removed deprecated Error constructor taking a line number instead of an attributes array.
• The deprecated Comment::getLine(), Comment::getTokenPos() and Comment::getFilePos() methods have been removed. Use Comment::getStartLine(), Comment::getStartTokenPos() and Comment::getStartFilePos() instead.
• Removed Stmt\Throw_ node, use Expr\Throw_ inside Stmt\Expression instead.
• Removed ParserFactory::create().

Fixed

• The pretty printer now uses a more accurate treatment of unary operator precedence, and will only wrap them in parentheses if required. This allowed fixing a number of other precedence related bugs.
• The pretty printer now respects the precedence of clone, throw and arrow functions.
• Fixed formatting preservation for alternative elseif/else syntax.
• Fixed checks for when it is safe to print strings as heredoc/nowdoc to accommodate flexible doc string semantics.
• Fixed various cases where \r at the end of a doc string could be incorrectly merged into a CRLF sequence with a following \n.
• __halt_compiler is no longer recognized as a semi-reserved keyword, in line with PHP behavior.
• <?= is no longer recognized as a semi-reserved keyword.
• Fix handling of very large overflowing \u escape sequences.
• Don't trim leading whitespace in formatting preserving printer.
• Treat DEL as a label character in the formatting preserving printer depending on the targeted PHP version.
• Fix error reporting in emulative lexer without explicitly specified error handler.
• Gracefully handle non-contiguous array indices in the Differ.

Deprecated

• The Node::getLine() method has been deprecated. Use Node::getStartLine() instead.