PHPFUI/InstaDoc

Abstract

Methods

public __construct(array $options = [])

Creates a pretty printer instance using the given options.

Supported options:

PhpVersion $phpVersion: The PHP version to target (default to PHP 7.4). This option controls compatibility of the generated code with older PHP versions in cases where a simple stylistic choice exists (e.g. array() vs []). It is safe to pretty-print an AST for a newer PHP version while specifying an older target (but the result will of course not be compatible with the older version in that case).
string $newline: The newline style to use. Should be "\n" (default) or "\r\n".
string $indent: The indentation to use. Should either be all spaces or a single tab. Defaults to four spaces (" ").
bool $shortArraySyntax: Whether to use [] instead of array() as the default array syntax, if the node does not specify a format. Defaults to whether the phpVersion support short array syntax.

param array{phpVersion?: \PhpVersion, newline?: string, indent?: string, shortArraySyntax?: bool} $options Dictionary of formatting options

public prettyPrint(array $stmts) : string

Pretty prints an array of statements.

param \Node[] $stmts Array of statements
return string Pretty printed statements

public prettyPrintExpr(PhpParser\Node\Expr $node) : string

Pretty prints an expression.

param \Expr $node Expression node
return string Pretty printed node

public prettyPrintFile(array $stmts) : string

Pretty prints a file of statements (includes the opening tag if it is required).

param \Node[] $stmts Array of statements
return string Pretty printed statements

public printFormatPreserving(array $stmts, array $origStmts, array $origTokens) : string

Perform a format-preserving pretty print of an AST.

The format preservation is best effort. For some changes to the AST the formatting will not be preserved (at least not locally).

In order to use this method a number of prerequisites must be satisfied:

The startTokenPos and endTokenPos attributes in the lexer must be enabled.
The CloningVisitor must be run on the AST prior to modification.
The original tokens must be provided, using the getTokens() method on the lexer.

param \Node[] $stmts Modified AST with links to original AST
param \Node[] $origStmts Original AST with token offset information
param \Token[] $origTokens Tokens of the original code

Constants

protected PhpParser\PrettyPrinterAbstract::FIXUP_BRACED_NAME = 6

protected PhpParser\PrettyPrinterAbstract::FIXUP_CALL_LHS = 3

protected PhpParser\PrettyPrinterAbstract::FIXUP_DEREF_LHS = 4

protected PhpParser\PrettyPrinterAbstract::FIXUP_ENCAPSED = 8

protected PhpParser\PrettyPrinterAbstract::FIXUP_NEW = 9

protected PhpParser\PrettyPrinterAbstract::FIXUP_PREC_LEFT = 0

protected PhpParser\PrettyPrinterAbstract::FIXUP_PREC_RIGHT = 1

protected PhpParser\PrettyPrinterAbstract::FIXUP_PREC_UNARY = 2

protected PhpParser\PrettyPrinterAbstract::FIXUP_STATIC_DEREF_LHS = 5

protected PhpParser\PrettyPrinterAbstract::FIXUP_VAR_BRACED_NAME = 7

protected PhpParser\PrettyPrinterAbstract::MAX_PRECEDENCE = 1000

Properties

protected bool $canUseSemicolonNamespaces

var bool Whether semicolon namespaces can be used (i.e. no global namespace is used)

protected ?string $docStringEndToken

var string|null Token placed at end of doc string to ensure it is followed by a newline. Null if flexible doc strings are used.

protected array $emptyListInsertionMap

var array<string,array{: int|string|null, : string, : string}>

protected array $fixupMap

var array<string,array<string,int>> Map from token classes and subnode names to FIXUP_* constants. This is used during format-preserving prints to place additional parens/braces if necessary.

protected int $indentLevel

var int Current indentation level.

protected array $insertionMap

var array<string,array{: int|string|null, : bool, : string|null, : string|null}> Map from "{$node->getType()}->{$subNode}" to [$find, $beforeToken, $extraLeft, $extraRight]. $find is an optional token after which the insertion occurs. $extraLeft/Right are optionally added before/after the main insertions.

protected array $labelCharMap

var array<string,bool> Map determining whether a certain character is a label character

protected array $listInsertionMap

var array<string,string> Map From "{$class}->{$subNode}" to string that should be inserted between elements of this list subnode.

protected array $modifierChangeMap

var array<string,array{: string, : int}> Map from "{$class}->{$subNode}" to [$printFn, $token] where $printFn is the function to print the modifiers and $token is the token before which the modifiers should be reprinted.

protected string $newline

var string Newline style. Does not include current indentation.

protected string $nl

var string Newline including current indentation.

protected PhpParser\Internal\Differ $nodeListDiffer

var \Internal\Differ<\Node> Differ for node lists

protected ?PhpParser\Internal\TokenStream $origTokens

var \TokenStream|null Original tokens for use in format-preserving pretty print

protected PhpParser\PhpVersion $phpVersion

var \PhpVersion PHP version to target

protected array $precedenceMap = ['PhpParser\Node\Expr\Clone_' => [-10, 0, 1], 'PhpParser\Node\Expr\BinaryOp\Pow' => [0, 0, 1], 'PhpParser\Node\Expr\BitwiseNot' => [10, -1, -1], 'PhpParser\Node\Expr\UnaryPlus' => [10, -1, -1], 'PhpParser\Node\Expr\UnaryMinus' => [10, -1, -1], 'PhpParser\Node\Expr\Cast\Int_' => [10, -1, -1], 'PhpParser\Node\Expr\Cast\Double' => [10, -1, -1], 'PhpParser\Node\Expr\Cast\String_' => [10, -1, -1], 'PhpParser\Node\Expr\Cast\Array_' => [10, -1, -1], 'PhpParser\Node\Expr\Cast\Object_' => [10, -1, -1], 'PhpParser\Node\Expr\Cast\Bool_' => [10, -1, -1], 'PhpParser\Node\Expr\Cast\Unset_' => [10, -1, -1], 'PhpParser\Node\Expr\ErrorSuppress' => [10, -1, -1], 'PhpParser\Node\Expr\Instanceof_' => [20, -1, -1], 'PhpParser\Node\Expr\BooleanNot' => [30, -1, -1], 'PhpParser\Node\Expr\BinaryOp\Mul' => [40, 41, 40], 'PhpParser\Node\Expr\BinaryOp\Div' => [40, 41, 40], 'PhpParser\Node\Expr\BinaryOp\Mod' => [40, 41, 40], 'PhpParser\Node\Expr\BinaryOp\Plus' => [50, 51, 50], 'PhpParser\Node\Expr\BinaryOp\Minus' => [50, 51, 50], 'PhpParser\Node\Expr\BinaryOp\Concat' => [50, 51, 50], 'PhpParser\Node\Expr\BinaryOp\ShiftLeft' => [60, 61, 60], 'PhpParser\Node\Expr\BinaryOp\ShiftRight' => [60, 61, 60], 'PhpParser\Node\Expr\BinaryOp\Smaller' => [70, 70, 70], 'PhpParser\Node\Expr\BinaryOp\SmallerOrEqual' => [70, 70, 70], 'PhpParser\Node\Expr\BinaryOp\Greater' => [70, 70, 70], 'PhpParser\Node\Expr\BinaryOp\GreaterOrEqual' => [70, 70, 70], 'PhpParser\Node\Expr\BinaryOp\Equal' => [80, 80, 80], 'PhpParser\Node\Expr\BinaryOp\NotEqual' => [80, 80, 80], 'PhpParser\Node\Expr\BinaryOp\Identical' => [80, 80, 80], 'PhpParser\Node\Expr\BinaryOp\NotIdentical' => [80, 80, 80], 'PhpParser\Node\Expr\BinaryOp\Spaceship' => [80, 80, 80], 'PhpParser\Node\Expr\BinaryOp\BitwiseAnd' => [90, 91, 90], 'PhpParser\Node\Expr\BinaryOp\BitwiseXor' => [100, 101, 100], 'PhpParser\Node\Expr\BinaryOp\BitwiseOr' => [110, 111, 110], 'PhpParser\Node\Expr\BinaryOp\BooleanAnd' => [120, 121, 120], 'PhpParser\Node\Expr\BinaryOp\BooleanOr' => [130, 131, 130], 'PhpParser\Node\Expr\BinaryOp\Coalesce' => [140, 140, 141], 'PhpParser\Node\Expr\Ternary' => [150, 150, 150], 'PhpParser\Node\Expr\Assign' => [160, -1, -1], 'PhpParser\Node\Expr\AssignRef' => [160, -1, -1], 'PhpParser\Node\Expr\AssignOp\Plus' => [160, -1, -1], 'PhpParser\Node\Expr\AssignOp\Minus' => [160, -1, -1], 'PhpParser\Node\Expr\AssignOp\Mul' => [160, -1, -1], 'PhpParser\Node\Expr\AssignOp\Div' => [160, -1, -1], 'PhpParser\Node\Expr\AssignOp\Concat' => [160, -1, -1], 'PhpParser\Node\Expr\AssignOp\Mod' => [160, -1, -1], 'PhpParser\Node\Expr\AssignOp\BitwiseAnd' => [160, -1, -1], 'PhpParser\Node\Expr\AssignOp\BitwiseOr' => [160, -1, -1], 'PhpParser\Node\Expr\AssignOp\BitwiseXor' => [160, -1, -1], 'PhpParser\Node\Expr\AssignOp\ShiftLeft' => [160, -1, -1], 'PhpParser\Node\Expr\AssignOp\ShiftRight' => [160, -1, -1], 'PhpParser\Node\Expr\AssignOp\Pow' => [160, -1, -1], 'PhpParser\Node\Expr\AssignOp\Coalesce' => [160, -1, -1], 'PhpParser\Node\Expr\YieldFrom' => [170, -1, -1], 'PhpParser\Node\Expr\Yield_' => [175, -1, -1], 'PhpParser\Node\Expr\Print_' => [180, -1, -1], 'PhpParser\Node\Expr\BinaryOp\LogicalAnd' => [190, 191, 190], 'PhpParser\Node\Expr\BinaryOp\LogicalXor' => [200, 201, 200], 'PhpParser\Node\Expr\BinaryOp\LogicalOr' => [210, 211, 210], 'PhpParser\Node\Expr\Include_' => [220, -1, -1], 'PhpParser\Node\Expr\ArrowFunction' => [230, -1, -1], 'PhpParser\Node\Expr\Throw_' => [240, -1, -1]]

var array<class-string,array{: int, : int, : int}>

protected array $removalMap

var array<string,array{left?: int|string, right?: int|string}> Map from "{$node->getType()}->{$subNode}" to ['left' => $l, 'right' => $r], where $l and $r specify the token type that needs to be stripped when removing this node.

protected bool $shortArraySyntax

var bool Whether to use short array syntax if the node specifies no preference

Methods

protected callLhsRequiresParens(PhpParser\Node $node) : bool

Determines whether the LHS of a call must be wrapped in parenthesis.

param \Node $node LHS of a call
return bool Whether parentheses are required

protected dereferenceLhsRequiresParens(PhpParser\Node $node) : bool

Determines whether the LHS of an array/object operation must be wrapped in parentheses.

param \Node $node LHS of dereferencing operation
return bool Whether parentheses are required

protected handleMagicTokens(string $str) : string

Handles (and removes) doc-string-end tokens.

protected indent() : void

Increase indentation level.

protected initializeEmptyListInsertionMap() : void

protected initializeFixupMap() : void

Lazily initializes fixup map.

The fixup map is used to determine whether a certain subnode of a certain node may require some kind of "fixup" operation, e.g. the addition of parenthesis or braces.

protected initializeInsertionMap() : void

protected initializeLabelCharMap() : void

Lazily initializes label char map.

The label char map determines whether a certain character may occur in a label.

protected initializeListInsertionMap() : void

protected initializeModifierChangeMap() : void

protected initializeNodeListDiffer() : void

Lazily initializes node list differ.

The node list differ is used to determine differences between two array subnodes.

protected initializeRemovalMap() : void

Lazily initializes the removal map.

The removal map is used to determine which additional tokens should be removed when a certain node is replaced by null.

protected isMultiline(array $nodes) : bool

Determine whether a list of nodes uses multiline formatting.

param (\Node|null)[] $nodes Node list
return bool Whether multiline formatting is used

protected newOperandRequiresParens(PhpParser\Node $node) : bool

Determines whether an expression used in "new" or "instanceof" requires parentheses.

param \Node $node New or instanceof operand
return bool Whether parentheses are required

protected outdent() : void

Decrease indentation level.

protected p(PhpParser\Node $node, int $precedence = 1000self::MAX_PRECEDENCE, int $lhsPrecedence = 1000self::MAX_PRECEDENCE, bool $parentFormatPreserved = false) : string

Pretty prints a node.

This method also handles formatting preservation for nodes.

param \Node $node Node to be pretty printed
param int $precedence Precedence of parent operator
param int $lhsPrecedence Precedence for unary operator on LHS of binary operator
param bool $parentFormatPreserved Whether parent node has preserved formatting
return string Pretty printed node

protected pArray(array $nodes, array $origNodes, int $pos, int $indentAdjustment, string $parentNodeClass, string $subNodeName, ?int $fixup) : ?string

Perform a format-preserving pretty print of an array.

param \Node[] $nodes New nodes
param \Node[] $origNodes Original nodes
param int $pos Current token position (updated by reference)
param int $indentAdjustment Adjustment for indentation
param string $parentNodeClass Class of the containing node.
param string $subNodeName Name of array subnode.
param null|int $fixup Fixup information for array item nodes
return null|string Result of pretty print or null if cannot preserve formatting

protected pCommaSeparated(array $nodes) : string

Pretty prints an array of nodes and implodes the printed values with commas.

param \Node[] $nodes Array of Nodes to be printed
return string Comma separated pretty printed nodes

protected pCommaSeparatedMultiline(array $nodes, bool $trailingComma) : string

Pretty prints a comma-separated list of nodes in multiline style, including comments.

The result includes a leading newline and one level of indentation (same as pStmts).

param \Node[] $nodes Array of Nodes to be printed
param bool $trailingComma Whether to use a trailing comma
return string Comma separated pretty printed nodes in multiline style

protected pComments(array $comments) : string

Prints reformatted text of the passed comments.

param \Comment[] $comments List of comments
return string Reformatted text of comments

protected pFallback(PhpParser\Node $node, int $precedence, int $lhsPrecedence) : string

protected pFixup(int $fixup, PhpParser\Node $subNode, ?string $parentClass, int $subStartPos, int $subEndPos) : string

Print node with fixups.

Fixups here refer to the addition of extra parentheses, braces or other characters, that are required to preserve program semantics in a certain context (e.g. to maintain precedence or because only certain expressions are allowed in certain places).

param int $fixup Fixup type
param \Node $subNode Subnode to print
param string|null $parentClass Class of parent node
param int $subStartPos Original start pos of subnode
param int $subEndPos Original end pos of subnode
return string Result of fixed-up print of subnode

protected pImplode(array $nodes, string $glue = '') : string

Pretty prints an array of nodes and implodes the printed values.

param \Node[] $nodes Array of Nodes to be printed
param string $glue Character to implode with
return string Imploded pretty printed nodes> $pre

protected pInfixOp(string $class, PhpParser\Node $leftNode, string $operatorString, PhpParser\Node $rightNode, int $precedence, int $lhsPrecedence) : string

Pretty-print an infix operation while taking precedence into account.

param string $class Node class of operator
param \Node $leftNode Left-hand side node
param string $operatorString String representation of the operator
param \Node $rightNode Right-hand side node
param int $precedence Precedence of parent operator
param int $lhsPrecedence Precedence for unary operator on LHS of binary operator
return string Pretty printed infix operation

protected pModifiers(int $modifiers) : string

Print modifiers, including trailing whitespace.

param int $modifiers Modifier mask to print
return string Printed modifiers

protected pPostfixOp(string $class, PhpParser\Node $node, string $operatorString, int $precedence, int $lhsPrecedence) : string

Pretty-print a postfix operation while taking precedence into account.

param string $class Node class of operator
param string $operatorString String representation of the operator
param \Node $node Node
param int $precedence Precedence of parent operator
param int $lhsPrecedence Precedence for unary operator on LHS of binary operator
return string Pretty printed postfix operation

protected pPrefixOp(string $class, string $operatorString, PhpParser\Node $node, int $precedence, int $lhsPrecedence) : string

Pretty-print a prefix operation while taking precedence into account.

param string $class Node class of operator
param string $operatorString String representation of the operator
param \Node $node Node
param int $precedence Precedence of parent operator
param int $lhsPrecedence Precedence for unary operator on LHS of binary operator
return string Pretty printed prefix operation

protected preprocessNodes(array $nodes) : void

Preprocesses the top-level nodes to initialize pretty printer state.

param \Node[] $nodes Array of nodes

protected pStatic(bool $static) : string

protected pStmts(array $nodes, bool $indent = true) : string

Pretty prints an array of nodes (statements) and indents them optionally.

param \Node[] $nodes Array of nodes
param bool $indent Whether to indent the printed nodes
return string Pretty printed statements

protected resetState() : void

Reset pretty printing state.

protected safeAppend(string $str, string $append) : void

Appends to a string, ensuring whitespace between label characters.

Example: "echo" and "$x" result in "echo$x", but "echo" and "x" result in "echo x". Without safeAppend the result would be "echox", which does not preserve semantics.

protected setIndentLevel(int $level) : void

Set indentation level

param int $level Level in number of spaces

protected staticDereferenceLhsRequiresParens(PhpParser\Node $node) : bool

Determines whether the LHS of a static operation must be wrapped in parentheses.

param \Node $node LHS of dereferencing operation
return bool Whether parentheses are required

Properties

private string $indent

var string String for single level of indentation

private int $indentWidth

var int Width in spaces to indent by.

private int $tabWidth = 4

var int Width in spaces of one tab.

private bool $useTabs

var bool Whether to use tab indentation.

ConfigurationCode Formating StyleTab Stop SpacesNumbers (0-9.) only