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 ]