6 Version 4.1.0 (2018-10-10)
7 --------------------------
11 * Added support for PHP 7.3 flexible heredoc/nowdoc strings, completing support for PHP 7.3. There
12 are two caveats for this feature:
13 * In some rare, pathological cases flexible heredoc/nowdoc strings change the interpretation of
14 existing doc strings. PHP-Parser will now use the new interpretation.
15 * Flexible heredoc/nowdoc strings require special support from the lexer. Because this is not
16 available on PHP versions before 7.3, support has to be emulated. This emulation is not perfect
17 and some cases which we do not expect to occur in practice (such as flexible doc strings being
18 nested within each other through abuse of variable-variable interpolation syntax) may not be
20 * Added `DONT_TRAVERSER_CURRENT_AND_CHILDREN` to `NodeTraverser` to skip both traversal of child
21 nodes, and prevent subsequent visitors from visiting the current node.
23 Version 4.0.4 (2018-09-18)
24 --------------------------
28 * The following methods have been added to `BuilderFactory`:
29 * `useTrait()` (fluent builder)
30 * `traitUseAdaptation()` (fluent builder)
31 * `useFunction()` (fluent builder)
32 * `useConst()` (fluent builder)
38 * `Builder\Param::setTypeHint()` has been deprecated in favor of the newly introduced
39 `Builder\Param::setType()`.
41 Version 4.0.3 (2018-07-15)
42 --------------------------
46 * Fixed possible undefined offset notice in formatting-preserving printer. (#513)
50 * Improved error recovery inside arrays.
51 * Preserve trailing comment inside classes. **Note:** This change is possibly BC breaking if your
52 code validates that classes can only contain certain statement types. After this change, classes
53 can also contain Nop statements, while this was not previously possible. (#509)
55 Version 4.0.2 (2018-06-03)
56 --------------------------
60 * Improved error recovery inside classes.
61 * Support error recovery for `foreach` without `as`.
62 * Support error recovery for parameters without variable (`function (Type ) {}`).
63 * Support error recovery for functions without body (`function ($foo)`).
65 Version 4.0.1 (2018-03-25)
66 --------------------------
70 * [PHP 7.3] Added support for trailing commas in function calls.
71 * [PHP 7.3] Added support for by-reference array destructuring.
72 * Added checks to node traverser to prevent replacing a statement with an expression or vice versa.
73 This should prevent common mistakes in the implementation of node visitors.
74 * Added the following methods to `BuilderFactory`, to simplify creation of expressions:
82 Version 4.0.0 (2018-02-28)
83 --------------------------
85 * No significant code changes since the beta 1 release.
87 Version 4.0.0-beta1 (2018-01-27)
88 --------------------------------
92 * In formatting-preserving pretty printer: Fixed indentation when inserting into lists. (#466)
96 * In formatting-preserving pretty printer: Improved formatting of elements inserted into multi-line
101 * The `Autoloader` class has been removed. It is now required to use the Composer autoloader.
103 Version 4.0.0-alpha3 (2017-12-26)
104 ---------------------------------
108 * In the formatting-preserving pretty printer:
109 * Fixed comment indentation.
110 * Fixed handling of inline HTML in the fallback case.
111 * Fixed insertion into list nodes that require creation of a code block.
115 * Added support for inserting at the start of list nodes in formatting-preserving pretty printer.
117 Version 4.0.0-alpha2 (2017-11-10)
118 ---------------------------------
122 * In the formatting-preserving pretty printer:
123 * Added support for changing modifiers.
124 * Added support for anonymous classes.
125 * Added support for removing from list nodes.
126 * Improved support for changing comments.
127 * Added start token offsets to comments.
129 Version 4.0.0-alpha1 (2017-10-18)
130 ---------------------------------
134 * Added experimental support for format-preserving pretty-printing. In this mode formatting will be
135 preserved for parts of the code which have not been modified.
136 * Added `replaceNodes` option to `NameResolver`, defaulting to true. If this option is disabled,
137 resolved names will be added as `resolvedName` attributes, instead of replacing the original
139 * Added `NodeFinder` class, which can be used to find nodes based on a callback or class name. This
140 is a utility to avoid custom node visitor implementations for simple search operations.
141 * Added `ClassMethod::isMagic()` method.
142 * Added `BuilderFactory` methods: `val()` method for creating an AST for a simple value, `concat()`
143 for creating concatenation trees, `args()` for preparing function arguments.
144 * Added `NameContext` class, which encapsulates the `NameResolver` logic independently of the actual
145 AST traversal. This facilitates use in other context, such as class names in doc comments.
146 Additionally it provides an API for getting the shortest representation of a name.
147 * Added `Node::setAttributes()` method.
148 * Added `JsonDecoder`. This allows conversion JSON back into an AST.
149 * Added `Name` methods `toLowerString()` and `isSpecialClassName()`.
150 * Added `Identifier` and `VarLikeIdentifier` nodes, which are used in place of simple strings in
152 * Added `getComments()`, `getStartLine()`, `getEndLine()`, `getStartTokenPos()`, `getEndTokenPos()`,
153 `getStartFilePos()` and `getEndFilePos()` methods to `Node`. These provide a more obvious access
154 point for the already existing attributes of the same name.
155 * Added `ConstExprEvaluator` to evaluate constant expressions to PHP values.
156 * Added `Expr\BinaryOp::getOperatorSigil()`, returning `+` for `Expr\BinaryOp\Plus`, etc.
160 * Many subnodes that previously held simple strings now use `Identifier` (or `VarLikeIdentifier`)
161 nodes. Please see the UPGRADE-4.0 file for an exhaustive list of affected nodes and some notes on
163 * Expression statements (`expr;`) are now represented using a `Stmt\Expression` node. Previously
164 these statements were directly represented as their constituent expression.
165 * The `name` subnode of `Param` has been renamed to `var` and now contains a `Variable` rather than
167 * The `name` subnode of `StaticVar` has been renamed to `var` and now contains a `Variable` rather
169 * The `var` subnode of `ClosureUse` now contains a `Variable` rather than a plain string.
170 * The `var` subnode of `Catch` now contains a `Variable` rather than a plain string.
171 * The `alias` subnode of `UseUse` is now `null` if no explicit alias is given. As such,
172 `use Foo\Bar` and `use Foo\Bar as Bar` are now represented differently. The `getAlias()` method
173 can be used to get the effective alias, even if it is not explicitly given.
177 * Support for running on PHP 5 and HHVM has been removed. You can however still parse code of old
178 PHP versions (such as PHP 5.2), while running on PHP 7.
179 * Removed `type` subnode on `Class`, `ClassMethod` and `Property` nodes. Use `flags` instead.
180 * The `ClassConst::isStatic()` method has been removed. Constants cannot have a static modifier.
181 * The `NodeTraverser` no longer accepts `false` as a return value from a `leaveNode()` method.
182 `NodeTraverser::REMOVE_NODE` should be returned instead.
183 * The `Node::setLine()` method has been removed. If you really need to, you can use `setAttribute()`
185 * The misspelled `Class_::VISIBILITY_MODIFER_MASK` constant has been dropped in favor of
186 `Class_::VISIBILITY_MODIFIER_MASK`.
187 * The XML serializer has been removed. As such, the classes `Serializer\XML`, and
188 `Unserializer\XML`, as well as the interfaces `Serializer` and `Unserializer` no longer exist.
189 * The `BuilderAbstract` class has been removed. It's functionality is moved into `BuilderHelpers`.
190 However, this is an internal class and should not be used directly.
192 Version 3.1.5 (2018-02-28)
193 --------------------------
197 * Fixed duplicate comment assignment in switch statements. (#469)
198 * Improve compatibility with PHP-Scoper. (#477)
200 Version 3.1.4 (2018-01-25)
201 --------------------------
205 * Fixed pretty printing of `-(-$x)` and `+(+$x)`. (#459)
207 Version 3.1.3 (2017-12-26)
208 --------------------------
212 * Improve compatibility with php-scoper, by supporting prefixed namespaces in
213 `NodeAbstract::getType()`.
215 Version 3.1.2 (2017-11-04)
216 --------------------------
220 * Comments on empty blocks are now preserved on a `Stmt\Nop` node. (#382)
224 * Added `kind` attribute for `Stmt\Namespace_` node, which is one of `KIND_SEMICOLON` or
225 `KIND_BRACED`. (#417)
226 * Added `setDocComment()` method to namespace builder. (#437)
228 Version 3.1.1 (2017-09-02)
229 --------------------------
233 * Fixed syntax error on comment after brace-style namespace declaration. (#412)
234 * Added support for TraitUse statements in trait builder. (#413)
236 Version 3.1.0 (2017-07-28)
237 --------------------------
241 * [PHP 7.2] Added support for trailing comma in group use statements.
242 * [PHP 7.2] Added support for `object` type. This means `object` types will now be represented as a
243 builtin type (a simple `"object"` string), rather than a class `Name`.
247 * Floating-point numbers are now printed correctly if the LC_NUMERIC locale uses a comma as decimal
252 * `Name::$parts` is no longer deprecated.
254 Version 3.0.6 (2017-06-28)
255 --------------------------
259 * Fixed the spelling of `Class_::VISIBILITY_MODIFIER_MASK`. The previous spelling of
260 `Class_::VISIBILITY_MODIFER_MASK` is preserved for backwards compatibility.
261 * The pretty printing will now preserve comments inside array literals and function calls by
262 printing the array items / function arguments on separate lines. Array literals and functions that
263 do not contain comments are not affected.
267 * Added `Builder\Param::makeVariadic()`.
271 * The `Node::setLine()` method has been deprecated.
273 Version 3.0.5 (2017-03-05)
274 --------------------------
278 * Name resolution of `NullableType`s is now performed earlier, so that a fully resolved signature is
279 available when a function is entered. (#360)
280 * `Error` nodes are now considered empty, while previously they extended until the token where the
281 error occurred. This made some nodes larger than expected. (#359)
282 * Fixed notices being thrown during error recovery in some situations. (#362)
284 Version 3.0.4 (2017-02-10)
285 --------------------------
289 * Fixed some extensibility issues in pretty printer (`pUseType()` is now public and `pPrec()` calls
290 into `p()`, instead of directly dispatching to the type-specific printing method).
291 * Fixed notice in `bin/php-parse` script.
295 * Error recovery from missing semicolons is now supported in more cases.
296 * Error recovery from trailing commas in positions where PHP does not support them is now supported.
298 Version 3.0.3 (2017-02-03)
299 --------------------------
303 * In `"$foo[0]"` the `0` is now parsed as an `LNumber` rather than `String`. (#325)
304 * Ensure integers and floats are always pretty printed preserving semantics, even if the particular
305 value can only be manually constructed.
306 * Throw a `LogicException` when trying to pretty-print an `Error` node. Previously this resulted in
307 an undefined method exception or fatal error.
311 * [PHP 7.1] Added support for negative interpolated offsets: `"$foo[-1]"`
312 * Added `preserveOriginalNames` option to `NameResolver`. If this option is enabled, an
313 `originalName` attribute, containing the unresolved name, will be added to each resolved name.
314 * Added `php-parse --with-positions` option, which dumps nodes with position information.
318 * The XML serializer has been deprecated. In particular, the classes `Serializer\XML`,
319 `Unserializer\XML`, as well as the interfaces `Serializer` and `Unserializer` are deprecated.
321 Version 3.0.2 (2016-12-06)
322 --------------------------
326 * Fixed name resolution of nullable types. (#324)
327 * Fixed pretty-printing of nullable types.
329 Version 3.0.1 (2016-12-01)
330 --------------------------
334 * Fixed handling of nested `list()`s: If the nested list was unkeyed, it was directly included in
335 the list items. If it was keyed, it was wrapped in `ArrayItem`. Now nested `List_` nodes are
336 always wrapped in `ArrayItem`s. (#321)
338 Version 3.0.0 (2016-11-30)
339 --------------------------
343 * Added support for dumping node positions in the NodeDumper through the `dumpPositions` option.
344 * Added error recovery support for `$`, `new`, `Foo::`.
346 Version 3.0.0-beta2 (2016-10-29)
347 --------------------------------
349 This release primarily improves our support for error recovery.
353 * Added `Node::setDocComment()` method.
354 * Added `Error::getMessageWithColumnInfo()` method.
355 * Added support for recovery from lexer errors.
356 * Added support for recovering from "special" errors (i.e. non-syntax parse errors).
357 * Added precise location information for lexer errors.
358 * Added `ErrorHandler` interface, and `ErrorHandler\Throwing` and `ErrorHandler\Collecting` as
359 specific implementations. These provide a general mechanism for handling error recovery.
360 * Added optional `ErrorHandler` argument to `Parser::parse()`, `Lexer::startLexing()` and
361 `NameResolver::__construct()`.
362 * The `NameResolver` now adds a `namespacedName` attribute on name nodes that cannot be statically
363 resolved (unqualified unaliased function or constant names in namespaces).
367 * Fixed attribute assignment for `GroupUse` prefix and variables in interpolated strings.
371 * The constants on `NameTraverserInterface` have been moved into the `NameTraverser` class.
372 * Due to the error handling changes, the `Parser` interface and `Lexer` API have changed.
373 * The emulative lexer now directly postprocesses tokens, instead of using `~__EMU__~` sequences.
374 This changes the protected API of the lexer.
375 * The `Name::slice()` method now returns `null` for empty slices, previously `new Name([])` was
376 used. `Name::concat()` now also supports concatenation with `null`.
380 * Removed `Name::append()` and `Name::prepend()`. These mutable methods have been superseded by
381 the immutable `Name::concat()`.
382 * Removed `Error::getRawLine()` and `Error::setRawLine()`. These methods have been superseded by
383 `Error::getStartLine()` and `Error::setStartLine()`.
384 * Removed support for node cloning in the `NodeTraverser`.
385 * Removed `$separator` argument from `Name::toString()`.
386 * Removed `throw_on_error` parser option and `Parser::getErrors()` method. Use the `ErrorHandler`
389 Version 3.0.0-beta1 (2016-09-16)
390 --------------------------------
394 * [7.1] Function/method and parameter builders now support PHP 7.1 type hints (void, iterable and
396 * Nodes and Comments now implement `JsonSerializable`. The node kind is stored in a `nodeType`
398 * The `InlineHTML` node now has an `hasLeadingNewline` attribute, that specifies whether the
399 preceding closing tag contained a newline. The pretty printer honors this attribute.
400 * Partial parsing of `$obj->` (with missing property name) is now supported in error recovery mode.
401 * The error recovery mode is now exposed in the `php-parse` script through the `--with-recovery`
404 The following changes are also part of PHP-Parser 2.1.1:
406 * The PHP 7 parser will now generate a parse error for `$var =& new Obj` assignments.
407 * Comments on free-standing code blocks will now be retained as comments on the first statement in
410 Version 3.0.0-alpha1 (2016-07-25)
411 ---------------------------------
415 * [7.1] Added support for `void` and `iterable` types. These will now be represented as strings
416 (instead of `Name` instances) similar to other builtin types.
417 * [7.1] Added support for class constant visibility. The `ClassConst` node now has a `flags` subnode
418 holding the visibility modifier, as well as `isPublic()`, `isProtected()` and `isPrivate()`
419 methods. The constructor changed to accept the additional subnode.
420 * [7.1] Added support for nullable types. These are represented using a new `NullableType` node
421 with a single `type` subnode.
422 * [7.1] Added support for short array destructuring syntax. This means that `Array` nodes may now
423 appear as the left-hand-side of assignments and foreach value targets. Additionally the array
424 items may now contain `null` values if elements are skipped.
425 * [7.1] Added support for keys in list() destructuring. The `List` subnode `vars` has been renamed
426 to `items` and now contains `ArrayItem`s instead of plain variables.
427 * [7.1] Added support for multi-catch. The `Catch` subnode `type` has been renamed to `types` and
428 is now an array of `Name`s.
429 * `Name::slice()` now supports lengths and negative offsets. This brings it in line with
430 `array_slice()` functionality.
434 Due to PHP 7.1 support additions described above, the node structure changed as follows:
436 * `void` and `iterable` types are now stored as strings if the PHP 7 parser is used.
437 * The `ClassConst` constructor changed to accept an additional `flags` subnode.
438 * The `Array` subnode `items` may now contain `null` elements (destructuring).
439 * The `List` subnode `vars` has been renamed to `items` and now contains `ArrayItem`s instead of
441 * The `Catch` subnode `type` has been renamed to `types` and is now an array of `Name`s.
443 Additionally the following changes were made:
445 * The `type` subnode on `Class`, `ClassMethod` and `Property` has been renamed to `flags`. The
446 `type` subnode has retained for backwards compatibility and is populated to the same value as
447 `flags`. However, writes to `type` will not update `flags`.
448 * The `TryCatch` subnode `finallyStmts` has been replaced with a `finally` subnode that holds an
449 explicit `Finally` node. This allows for more accurate attribute assignment.
450 * The `Trait` constructor now has the same form as the `Class` and `Interface` constructors: It
451 takes an array of subnodes. Unlike classes/interfaces, traits can only have a `stmts` subnode.
452 * The `NodeDumper` now prints class/method/property/constant modifiers, as well as the include and
453 use type in a textual representation, instead of only showing the number.
454 * All methods on `PrettyPrinter\Standard` are now protected. Previously most of them were public.
458 * Removed support for running on PHP 5.4. It is however still possible to parse PHP 5.2-5.4 code
459 while running on a newer version.
460 * The deprecated `Comment::setLine()` and `Comment::setText()` methods have been removed.
461 * The deprecated `Name::set()`, `Name::setFirst()` and `Name::setLast()` methods have been removed.
463 Version 2.1.1 (2016-09-16)
464 --------------------------
468 * The pretty printer will now escape all control characters in the range `\x00-\x1F` inside double
469 quoted strings. If no special escape sequence is available, an octal escape will be used.
470 * The quality of the error recovery has been improved. In particular unterminated expressions should
471 be handled more gracefully.
472 * The PHP 7 parser will now generate a parse error for `$var =& new Obj` assignments.
473 * Comments on free-standing code blocks will no be retained as comments on the first statement in
476 Version 2.1.0 (2016-04-19)
477 --------------------------
481 * Properly support `B""` strings (with uppercase `B`) in a number of places.
482 * Fixed reformatting of indented parts in a certain non-standard comment style.
486 * Added `dumpComments` option to node dumper, to enable dumping of comments associated with nodes.
487 * Added `Stmt\Nop` node, that is used to collect comments located at the end of a block or at the
488 end of a file (without a following node with which they could otherwise be associated).
489 * Added `kind` attribute to `Expr\Exit` to distinguish between `exit` and `die`.
490 * Added `kind` attribute to `Scalar\LNumber` to distinguish between decimal, binary, octal and
492 * Added `kind` attribute to `Expr\Array` to distinguish between `array()` and `[]`.
493 * Added `kind` attribute to `Scalar\String` and `Scalar\Encapsed` to distinguish between
494 single-quoted, double-quoted, heredoc and nowdoc string.
495 * Added `docLabel` attribute to `Scalar\String` and `Scalar\Encapsed`, if it is a heredoc or
497 * Added start file offset information to `Comment` nodes.
498 * Added `setReturnType()` method to function and method builders.
499 * Added `-h` and `--help` options to `php-parse` script.
503 * Invalid octal literals now throw a parse error in PHP 7 mode.
504 * The pretty printer takes all the new attributes mentioned in the previous section into account.
505 * The protected `AbstractPrettyPrinter::pComments()` method no longer returns a trailing newline.
506 * The bundled autoloader supports library files being stored in a different directory than
507 `PhpParser` for easier downstream distribution.
511 * The `Comment::setLine()` and `Comment::setText()` methods have been deprecated. Construct new
516 * The internal (but public) method `Scalar\LNumber::parse()` has been removed. A non-internal
517 `LNumber::fromString()` method has been added instead.
519 Version 2.0.1 (2016-02-28)
520 --------------------------
524 * `declare() {}` and `declare();` are not semantically equivalent and will now result in different
525 ASTs. The format case will have an empty `stmts` array, while the latter will set `stmts` to
527 * Magic constants are now supported as semi-reserved keywords.
528 * A shebang line like `#!/usr/bin/env php` is now allowed at the start of a namespaced file.
529 Previously this generated an exception.
530 * The `prettyPrintFile()` method will not strip a trailing `?>` from the raw data that follows a
531 `__halt_compiler()` statement.
532 * The `prettyPrintFile()` method will not strip an opening `<?php` if the file starts with a
533 comment followed by InlineHTML.
535 Version 2.0.0 (2015-12-04)
536 --------------------------
540 * String parts of encapsed strings are now represented using `Scalar\EncapsStringPart` nodes.
541 Previously raw strings were used. This affects the `parts` child of `Scalar\Encaps` and
542 `Expr\ShellExec`. The change has been done to allow assignment of attributes to encapsed string
545 Version 2.0.0-beta1 (2015-10-21)
546 --------------------------------
550 * Fixed issue with too many newlines being stripped at the end of heredoc/nowdoc strings in some
555 * Update group use support to be in line with recent PHP 7.0 builds.
556 * Renamed `php-parse.php` to `php-parse` and registered it as a composer bin.
557 * Use composer PSR-4 autoloader instead of custom autoloader.
558 * Specify phpunit as a dev dependency.
562 * Added `shortArraySyntax` option to pretty printer, to print all arrays using short syntax.
564 Version 2.0.0-alpha1 (2015-07-14)
565 ---------------------------------
567 A more detailed description of backwards incompatible changes can be found in the
568 [upgrading guide](UPGRADE-2.0.md).
572 * Removed support for running on PHP 5.3. It is however still possible to parse PHP 5.2 and PHP 5.3
573 code while running on a newer version.
574 * Removed legacy class name aliases. This includes the old non-namespaced class names and the old
575 names for classes that were renamed for PHP 7 compatibility.
576 * Removed support for legacy node format. All nodes must have a `getSubNodeNames()` method now.
580 * Added support for remaining PHP 7 features that were not present in 1.x:
581 * Group use declarations. These are represented using `Stmt\GroupUse` nodes. Furthermore a `type`
582 attribute was added to `Stmt\UseUse` to handle mixed group use declarations.
583 * Uniform variable syntax.
584 * Generalized yield operator.
585 * Scalar type declarations. These are presented using `'bool'`, `'int'`, `'float'` and `'string'`
586 as the type. The PHP 5 parser also accepts these, however they'll be `Name` instances there.
587 * Unicode escape sequences.
588 * Added `PhpParser\ParserFactory` class, which should be used to create parser instances.
589 * Added `Name::concat()` which concatenates two names.
590 * Added `Name->slice()` which takes a subslice of a name.
594 * `PhpParser\Parser` is now an interface, implemented by `Parser\Php5`, `Parser\Php7` and
595 `Parser\Multiple`. The `Multiple` parser will try multiple parsers, until one succeeds.
596 * Token constants are now defined on `PhpParser\Parser\Tokens` rather than `PhpParser\Parser`.
597 * The `Name->set()`, `Name->append()`, `Name->prepend()` and `Name->setFirst()` methods are
598 deprecated in favor of `Name::concat()` and `Name->slice()`.
599 * The `NodeTraverser` no longer clones nodes by default. The old behavior can be restored by
600 passing `true` to the constructor.
601 * The constructor for `Scalar` nodes no longer has a default value. E.g. `new LNumber()` should now
602 be written as `new LNumber(0)`.
606 **This changelog only includes changes from the 2.0 series. For older changes see the
607 [1.x series changelog](https://github.com/nikic/PHP-Parser/blob/1.x/CHANGELOG.md) and the
608 [0.9 series changelog](https://github.com/nikic/PHP-Parser/blob/0.9/CHANGELOG.md).**