Each ? placeholder in $template is consumed in left-to-right order and substituted with a fresh bind reference (@value1, @value2, …). The corresponding values are stored in the resulting bindVars map so they are serialised safely by the server-side bind resolver — there is no way to provoke AQL injection through this layer.

Two value types receive special treatment:

• AqlLiteral — inlined verbatim into the query (no bind). Use this for AQL keywords / function names that cannot be parameterised. Build one with aqlLiteral().
• Anything else (scalar, array, null) — bound as a value parameter.

When the caller wants to bind a collection (using the @@name double-@ syntax), the resulting AqlQuery should be assembled manually (or via the existing query-builder helpers) rather than through this helper, which only emits single-@ value binds.

Example:

$minAge    = 18 ;
$direction = aqlLiteral( 'DESC' ) ; // safe to inline because whitelisted

$query = aql
(
    'FOR u IN users FILTER u.age > ? SORT u.name ? RETURN u' ,
    $minAge ,
    $direction ,
) ;

// $query->query    === 'FOR u IN users FILTER u.age > @value1 SORT u.name DESC RETURN u'
// $query->bindVars === [ 'value1' => 18 ]

Wraps a raw AQL fragment so that aql() interpolates it verbatim into the resulting query string instead of binding it as a parameter. The fragment MUST come from a trusted source (validated whitelist, server-side enum, …) — never from raw user input.

Example:

$cursor = $db->query
(
    aql( 'FOR u IN users SORT u.name ? RETURN u' , aqlLiteral( 'DESC' ) )
) ;
// → "FOR u IN users SORT u.name DESC RETURN u"

Each entry of $fragments is interpreted the same way the aql() helper interprets a value passed in its variadic tail:

• AqlQuery — query string interpolated as-is, bind variables merged into the resulting AqlQuery (with per-fragment renaming on collision — see below).
• AqlLiteral — value inlined verbatim into the query string, no bind.
• Anything else — bound as a value parameter (@jN).

Bind name collisions across fragments are resolved by prefixing the offending names with j{index}_ — the references inside the offending fragment's query string are rewritten to match. The reserved single-@ vs double-@@ syntax used to distinguish value binds from collection binds is preserved.

Empty input returns an empty AqlQuery; a single-entry input goes through the same machinery so the caller can rely on the bind map being well-formed regardless of $fragments length.

Example — assembling N optional FILTER conditions:

$filters = [] ;

if ( $onlyAdmins )  { $filters[] = aql( 'FILTER u.role == ?'   , 'admin' ) ; }
if ( $onlyActive )  { $filters[] = aql( 'FILTER u.active == ?' , true    ) ; }

$query = aql
(
    'FOR u IN users ? RETURN u' ,
    new AqlLiteral( join( $filters )->query ) ,
) ;
// (Or, more directly, assemble through Database::query() with a manually
//  built AqlQuery merging the joined fragment + the rest.)

The separator defaults to a single space (mirroring arangojs aql.join); pass an explicit value to interleave keywords (' AND ', ', ', …).