Visitor
in package
Utility for efficient AST traversal and modification.
visit()
will walk through an AST using a depth first traversal, calling
the visitor's enter function at each node in the traversal, and calling the
leave function after visiting that node and all of it's child nodes.
By returning different values from the enter and leave functions, the behavior of the visitor can be altered, including skipping over a sub-tree of the AST (by returning false), editing the AST by returning a value or null to remove the value, or to stop the whole traversal by returning BREAK.
When using visit()
to edit an AST, the original AST will not be modified, and
a new version of the AST with the changes applied will be returned from the
visit function.
$editedAST = Visitor::visit($ast, [
'enter' => function ($node, $key, $parent, $path, $ancestors) {
// return
// null: no action
// Visitor::skipNode(): skip visiting this node
// Visitor::stop(): stop visiting altogether
// Visitor::removeNode(): delete this node
// any value: replace this node with the returned value
},
'leave' => function ($node, $key, $parent, $path, $ancestors) {
// return
// null: no action
// Visitor::stop(): stop visiting altogether
// Visitor::removeNode(): delete this node
// any value: replace this node with the returned value
}
]);
Alternatively to providing enter() and leave() functions, a visitor can instead provide functions named the same as the kinds of AST nodes, or enter/leave visitors at a named key, leading to four permutations of visitor API:
-
Named visitors triggered when entering a node a specific kind.
Visitor::visit($ast, [ 'Kind' => function ($node) { // enter the "Kind" node } ]);
-
Named visitors that trigger upon entering and leaving a node of a specific kind.
Visitor::visit($ast, [ 'Kind' => [ 'enter' => function ($node) { // enter the "Kind" node } 'leave' => function ($node) { // leave the "Kind" node } ] ]);
-
Generic visitors that trigger upon entering and leaving any node.
Visitor::visit($ast, [ 'enter' => function ($node) { // enter any node }, 'leave' => function ($node) { // leave any node } ]);
-
Parallel visitors for entering and leaving nodes of a specific kind.
Visitor::visit($ast, [ 'enter' => [ 'Kind' => function($node) { // enter the "Kind" node } }, 'leave' => [ 'Kind' => function ($node) { // leave the "Kind" node } ] ]);
Table of Contents
- $visitorKeys : array<string|int, array<string|int, string>>
- getVisitFn() : callable|null
- removeNode() : VisitorOperation
- Returns marker for removing a node
- skipNode() : VisitorOperation
- Returns marker for skipping current node
- stop() : VisitorOperation
- Returns marker for visitor break
- visit() : Node|mixed
- Visit the AST (see class description for details)
- visitInParallel() : array<string, callable>
- visitWithTypeInfo() : mixed
- Creates a new visitor instance which maintains a provided TypeInfo instance along with visiting visitor.
Properties
$visitorKeys
public
static array<string|int, array<string|int, string>>
$visitorKeys
= [\GraphQL\Language\AST\NodeKind::NAME => [], \GraphQL\Language\AST\NodeKind::DOCUMENT => ['definitions'], \GraphQL\Language\AST\NodeKind::OPERATION_DEFINITION => ['name', 'variableDefinitions', 'directives', 'selectionSet'], \GraphQL\Language\AST\NodeKind::VARIABLE_DEFINITION => ['variable', 'type', 'defaultValue', 'directives'], \GraphQL\Language\AST\NodeKind::VARIABLE => ['name'], \GraphQL\Language\AST\NodeKind::SELECTION_SET => ['selections'], \GraphQL\Language\AST\NodeKind::FIELD => ['alias', 'name', 'arguments', 'directives', 'selectionSet'], \GraphQL\Language\AST\NodeKind::ARGUMENT => ['name', 'value'], \GraphQL\Language\AST\NodeKind::FRAGMENT_SPREAD => ['name', 'directives'], \GraphQL\Language\AST\NodeKind::INLINE_FRAGMENT => ['typeCondition', 'directives', 'selectionSet'], \GraphQL\Language\AST\NodeKind::FRAGMENT_DEFINITION => [
'name',
// Note: fragment variable definitions are experimental and may be changed
// or removed in the future.
'variableDefinitions',
'typeCondition',
'directives',
'selectionSet',
], \GraphQL\Language\AST\NodeKind::INT => [], \GraphQL\Language\AST\NodeKind::FLOAT => [], \GraphQL\Language\AST\NodeKind::STRING => [], \GraphQL\Language\AST\NodeKind::BOOLEAN => [], \GraphQL\Language\AST\NodeKind::NULL => [], \GraphQL\Language\AST\NodeKind::ENUM => [], \GraphQL\Language\AST\NodeKind::LST => ['values'], \GraphQL\Language\AST\NodeKind::OBJECT => ['fields'], \GraphQL\Language\AST\NodeKind::OBJECT_FIELD => ['name', 'value'], \GraphQL\Language\AST\NodeKind::DIRECTIVE => ['name', 'arguments'], \GraphQL\Language\AST\NodeKind::NAMED_TYPE => ['name'], \GraphQL\Language\AST\NodeKind::LIST_TYPE => ['type'], \GraphQL\Language\AST\NodeKind::NON_NULL_TYPE => ['type'], \GraphQL\Language\AST\NodeKind::SCHEMA_DEFINITION => ['directives', 'operationTypes'], \GraphQL\Language\AST\NodeKind::OPERATION_TYPE_DEFINITION => ['type'], \GraphQL\Language\AST\NodeKind::SCALAR_TYPE_DEFINITION => ['description', 'name', 'directives'], \GraphQL\Language\AST\NodeKind::OBJECT_TYPE_DEFINITION => ['description', 'name', 'interfaces', 'directives', 'fields'], \GraphQL\Language\AST\NodeKind::FIELD_DEFINITION => ['description', 'name', 'arguments', 'type', 'directives'], \GraphQL\Language\AST\NodeKind::INPUT_VALUE_DEFINITION => ['description', 'name', 'type', 'defaultValue', 'directives'], \GraphQL\Language\AST\NodeKind::INTERFACE_TYPE_DEFINITION => ['description', 'name', 'interfaces', 'directives', 'fields'], \GraphQL\Language\AST\NodeKind::UNION_TYPE_DEFINITION => ['description', 'name', 'directives', 'types'], \GraphQL\Language\AST\NodeKind::ENUM_TYPE_DEFINITION => ['description', 'name', 'directives', 'values'], \GraphQL\Language\AST\NodeKind::ENUM_VALUE_DEFINITION => ['description', 'name', 'directives'], \GraphQL\Language\AST\NodeKind::INPUT_OBJECT_TYPE_DEFINITION => ['description', 'name', 'directives', 'fields'], \GraphQL\Language\AST\NodeKind::SCALAR_TYPE_EXTENSION => ['name', 'directives'], \GraphQL\Language\AST\NodeKind::OBJECT_TYPE_EXTENSION => ['name', 'interfaces', 'directives', 'fields'], \GraphQL\Language\AST\NodeKind::INTERFACE_TYPE_EXTENSION => ['name', 'interfaces', 'directives', 'fields'], \GraphQL\Language\AST\NodeKind::UNION_TYPE_EXTENSION => ['name', 'directives', 'types'], \GraphQL\Language\AST\NodeKind::ENUM_TYPE_EXTENSION => ['name', 'directives', 'values'], \GraphQL\Language\AST\NodeKind::INPUT_OBJECT_TYPE_EXTENSION => ['name', 'directives', 'fields'], \GraphQL\Language\AST\NodeKind::DIRECTIVE_DEFINITION => ['description', 'name', 'arguments', 'locations'], \GraphQL\Language\AST\NodeKind::SCHEMA_EXTENSION => ['directives', 'operationTypes']]
Methods
getVisitFn()
public
static getVisitFn(array<string|int, callable>|null $visitor, string $kind, bool $isLeaving) : callable|null
Parameters
- $visitor : array<string|int, callable>|null
- $kind : string
- $isLeaving : bool
Return values
callable|null —removeNode()
Returns marker for removing a node
public
static removeNode() : VisitorOperation
Return values
VisitorOperation —skipNode()
Returns marker for skipping current node
public
static skipNode() : VisitorOperation
Return values
VisitorOperation —stop()
Returns marker for visitor break
public
static stop() : VisitorOperation
Return values
VisitorOperation —visit()
Visit the AST (see class description for details)
public
static visit(Node|ArrayObject|stdClass $root, array<string|int, callable> $visitor[, array<string|int, mixed>|null $keyMap = null ]) : Node|mixed
Parameters
- $root : Node|ArrayObject|stdClass
- $visitor : array<string|int, callable>
- $keyMap : array<string|int, mixed>|null = null
Tags
Return values
Node|mixed —visitInParallel()
public
static visitInParallel(array<string|int, array<string|int, callable>> $visitors) : array<string, callable>
Parameters
- $visitors : array<string|int, array<string|int, callable>>
Return values
array<string, callable> —visitWithTypeInfo()
Creates a new visitor instance which maintains a provided TypeInfo instance along with visiting visitor.
public
static visitWithTypeInfo(TypeInfo $typeInfo, mixed $visitor) : mixed
Parameters
- $typeInfo : TypeInfo
- $visitor : mixed