Chris@0: Upgrading from PHP-Parser 0.9 to 1.0
Chris@0: ====================================
Chris@0: 
Chris@0: ### PHP version requirements
Chris@0: 
Chris@0: PHP-Parser now requires PHP 5.3 or newer to run. It is however still possible to *parse* PHP 5.2 source code, while
Chris@0: running on a newer version.
Chris@0: 
Chris@0: ### Move to namespaced names
Chris@0: 
Chris@0: The library has been moved to use namespaces with the `PhpParser` vendor prefix. However, the old names using
Chris@0: underscores are still available as aliases, as such most code should continue running on the new version without
Chris@0: further changes.
Chris@0: 
Chris@0: Old (still works, but discouraged):
Chris@0: 
Chris@0: ```php
Chris@0: $parser = new \PHPParser_Parser(new \PHPParser_Lexer_Emulative);
Chris@0: $prettyPrinter = new \PHPParser_PrettyPrinter_Default;
Chris@0: ```
Chris@0: 
Chris@0: New:
Chris@0: 
Chris@0: ```php
Chris@0: $parser = new \PhpParser\Parser(new PhpParser\Lexer\Emulative);
Chris@0: $prettyPrinter = new \PhpParser\PrettyPrinter\Standard;
Chris@0: ```
Chris@0: 
Chris@0: Note that the `PHPParser` prefix was changed to `PhpParser`. While PHP class names are technically case-insensitive,
Chris@0: the autoloader will not be able to load `PHPParser\Parser` or other case variants.
Chris@0: 
Chris@0: Due to conflicts with reserved keywords, some class names now end with an underscore, e.g. `PHPParser_Node_Stmt_Class`
Chris@0: is now `PhpParser\Node\Stmt\Class_`. (But as usual, the old name is still available.)
Chris@0: 
Chris@0: ### Changes to `Node::getType()`
Chris@0: 
Chris@0: The `Node::getType()` method continues to return names using underscores instead of namespace separators and also does
Chris@0: not contain the trailing underscore that may be present in the class name. As such its output will not change in many
Chris@0: cases.
Chris@0: 
Chris@0: However, some node classes have been moved to a different namespace or renamed, which will result in a different
Chris@0: `Node::getType()` output:
Chris@0: 
Chris@0: ```
Chris@0: Expr_AssignBitwiseAnd => Expr_AssignOp_BitwiseAnd
Chris@0: Expr_AssignBitwiseOr  => Expr_AssignOp_BitwiseOr
Chris@0: Expr_AssignBitwiseXor => Expr_AssignOp_BitwiseXor
Chris@0: Expr_AssignConcat     => Expr_AssignOp_Concat
Chris@0: Expr_AssignDiv        => Expr_AssignOp_Div
Chris@0: Expr_AssignMinus      => Expr_AssignOp_Minus
Chris@0: Expr_AssignMod        => Expr_AssignOp_Mod
Chris@0: Expr_AssignMul        => Expr_AssignOp_Mul
Chris@0: Expr_AssignPlus       => Expr_AssignOp_Plus
Chris@0: Expr_AssignShiftLeft  => Expr_AssignOp_ShiftLeft
Chris@0: Expr_AssignShiftRight => Expr_AssignOp_ShiftRight
Chris@0: 
Chris@0: Expr_BitwiseAnd       => Expr_BinaryOp_BitwiseAnd
Chris@0: Expr_BitwiseOr        => Expr_BinaryOp_BitwiseOr
Chris@0: Expr_BitwiseXor       => Expr_BinaryOp_BitwiseXor
Chris@0: Expr_BooleanAnd       => Expr_BinaryOp_BooleanAnd
Chris@0: Expr_BooleanOr        => Expr_BinaryOp_BooleanOr
Chris@0: Expr_Concat           => Expr_BinaryOp_Concat
Chris@0: Expr_Div              => Expr_BinaryOp_Div
Chris@0: Expr_Equal            => Expr_BinaryOp_Equal
Chris@0: Expr_Greater          => Expr_BinaryOp_Greater
Chris@0: Expr_GreaterOrEqual   => Expr_BinaryOp_GreaterOrEqual
Chris@0: Expr_Identical        => Expr_BinaryOp_Identical
Chris@0: Expr_LogicalAnd       => Expr_BinaryOp_LogicalAnd
Chris@0: Expr_LogicalOr        => Expr_BinaryOp_LogicalOr
Chris@0: Expr_LogicalXor       => Expr_BinaryOp_LogicalXor
Chris@0: Expr_Minus            => Expr_BinaryOp_Minus
Chris@0: Expr_Mod              => Expr_BinaryOp_Mod
Chris@0: Expr_Mul              => Expr_BinaryOp_Mul
Chris@0: Expr_NotEqual         => Expr_BinaryOp_NotEqual
Chris@0: Expr_NotIdentical     => Expr_BinaryOp_NotIdentical
Chris@0: Expr_Plus             => Expr_BinaryOp_Plus
Chris@0: Expr_ShiftLeft        => Expr_BinaryOp_ShiftLeft
Chris@0: Expr_ShiftRight       => Expr_BinaryOp_ShiftRight
Chris@0: Expr_Smaller          => Expr_BinaryOp_Smaller
Chris@0: Expr_SmallerOrEqual   => Expr_BinaryOp_SmallerOrEqual
Chris@0: 
Chris@0: Scalar_ClassConst     => Scalar_MagicConst_Class
Chris@0: Scalar_DirConst       => Scalar_MagicConst_Dir
Chris@0: Scalar_FileConst      => Scalar_MagicConst_File
Chris@0: Scalar_FuncConst      => Scalar_MagicConst_Function
Chris@0: Scalar_LineConst      => Scalar_MagicConst_Line
Chris@0: Scalar_MethodConst    => Scalar_MagicConst_Method
Chris@0: Scalar_NSConst        => Scalar_MagicConst_Namespace
Chris@0: Scalar_TraitConst     => Scalar_MagicConst_Trait
Chris@0: ```
Chris@0: 
Chris@0: These changes may affect custom pretty printers and code comparing the return value of `Node::getType()` to specific
Chris@0: strings.
Chris@0: 
Chris@0: ### Miscellaneous
Chris@0: 
Chris@0:   * The classes `Template` and `TemplateLoader` have been removed. You should use some other [code generation][code_gen]
Chris@0:     project built on top of PHP-Parser instead.
Chris@0: 
Chris@0:   * The `PrettyPrinterAbstract::pStmts()` method now emits a leading newline if the statement list is not empty.
Chris@0:     Custom pretty printers should remove the explicit newline before `pStmts()` calls.
Chris@0: 
Chris@0:     Old:
Chris@0: 
Chris@0:     ```php
Chris@0:     public function pStmt_Trait(PHPParser_Node_Stmt_Trait $node) {
Chris@0:         return 'trait ' . $node->name
Chris@0:              . "\n" . '{' . "\n" . $this->pStmts($node->stmts) . "\n" . '}';
Chris@0:     }
Chris@0:     ```
Chris@0: 
Chris@0:     New:
Chris@0: 
Chris@0:     ```php
Chris@0:     public function pStmt_Trait(Stmt\Trait_ $node) {
Chris@0:         return 'trait ' . $node->name
Chris@0:              . "\n" . '{' . $this->pStmts($node->stmts) . "\n" . '}';
Chris@0:     }
Chris@0:     ```
Chris@0: 
Chris@0:   [code_gen]: https://github.com/nikic/PHP-Parser/wiki/Projects-using-the-PHP-Parser#code-generation