This helper constructs the canonical Arango Query Language (AQL) traversal expression, optionally including depth ranges, edge collections or graph names, direction, and bind variables.

It supports flexible initialization via the $init array, automatic bind variable injection, and seamless hydration of traversal options via TraversalOptions.

🧩 Canonical Form

FOR <vertexRef>, <edgeRef>, <pathRef>
IN <minDepth>..<maxDepth> <direction> <startVertex>
GRAPH <graphName>
OPTIONS { ... }

or, when using edge collections instead of a graph:

FOR <vertexRef>, <edgeRef>, <pathRef>
IN <minDepth>..<maxDepth> <direction> <startVertex>
<edgeCollection1>, <edgeCollection2>, ...

🔒 Bind Variables

If $binds is provided, both AQL::GRAPH and AQL::START_VERTEX (and optionally AQL::EDGE_COLLECTION) are automatically bound using aqlBind(), ensuring safe, injection-free query generation.

Example of secure binding:

$binds = [];
$aql = aqlTraversal([
AQL::GRAPH        => 'socialGraph',
AQL::START_VERTEX => '@start',
AQL::DIRECTION    => Traversal::INBOUND
], $binds);

print_r($binds);
// ['@start' => 'users/123', '@graph' => 'socialGraph']

💡 Usage Examples

1 - Simple graph traversal

echo aqlTraversal
([
    AQL::GRAPH         => 'socialGraph',
    AQL::START_VERTEX  => 'users/123',
]);
// FOR vertex IN OUTBOUND 'users/123' GRAPH 'socialGraph'

2 - Traversal with edges and path references

echo aqlTraversal
([
    AQL::VERTEX_REF    => 'v',
    AQL::EDGE_REF      => 'e',
    AQL::PATH_REF      => 'p',
    AQL::DIRECTION     => Traversal::INBOUND,
    AQL::GRAPH         => 'organization',
    AQL::START_VERTEX  => 'employees/42',
]);
// FOR v, e, p IN INBOUND 'employees/42' GRAPH 'organization'

3 - Depth-limited traversal

echo aqlTraversal
([
    AQL::GRAPH         => 'socialGraph',
    AQL::START_VERTEX  => 'users/123',
    AQL::MIN_DEPTH     => 1,
    AQL::MAX_DEPTH     => 3,
]);
// FOR vertex IN 1..3 OUTBOUND 'users/123' GRAPH 'socialGraph'

4 - Traversal using multiple edge collections

echo aqlTraversal
([
    AQL::EDGE_COLLECTION => ['follows', 'likes'],
    AQL::START_VERTEX    => 'users/123',
    AQL::DIRECTION       => Traversal::OUTBOUND,
]);
// FOR vertex IN OUTBOUND 'users/123' follows, likes

5 - With PRUNE condition

echo aqlTraversal
([
    AQL::GRAPH         => 'socialGraph',
    AQL::START_VERTEX  => 'users/123',
    AQL::PRUNE         => 'vertex.age < 18',
]);
// FOR vertex IN OUTBOUND 'users/123' GRAPH 'socialGraph' PRUNE vertex.age < 18

6 - With OPTIONS

echo aqlTraversal
([
    AQL::GRAPH         => 'companyGraph',
    AQL::START_VERTEX  => 'departments/1',
    AQL::OPTIONS       => ['bfs' => true, 'uniqueVertices' => 'global'],
]);
// FOR vertex IN OUTBOUND 'departments/1' GRAPH 'companyGraph' OPTIONS { "bfs": true, "uniqueVertices": "global" }