This helper converts various PHP values to their AQL array representation. Objects are cast to arrays, arrays are JSON-encoded, strings are returned as-is, and other values return an empty array expression.

This is used for COLLECT ... ASSIGN, COLLECT ... AGGREGATE, FOR ... UPDATE, FOR ... REPLACE, etc.

Accepts:

• associative arrays: ['key' => value, ...]
• indexed arrays of [key, value] pairs: [['key', value], ...]
• objects: converted to associative arrays
• strings: returned as-is inside braces
• null: returns '}'

Options can be passed as an associative array:

• 'useSpace' : bool, add spaces around braces and after commas
• 'rawValues' : array, keys whose values should be treated as raw AQL expressions
• 'rawKeys' : array, keys which should be kept raw (their values are not wrapped or converted)

Accepts either:

• A string representing a raw AQL expression, returned as-is.
• An array or object representing key-value pairs, converted into an AQL document object using aqlDocument().
• null, which results in a null return value.

Internally, this function delegates to aqlDocument() when $value is an array or object, and otherwise returns the raw string.

Examples:

echo aqlExpression( "FOR u IN users RETURN u" )               ; // "FOR u IN users RETURN u"
echo aqlExpression( ['name' => 'John', 'age' => 30] )        ; // "{name:'John',age:30}"
echo aqlExpression( [['status', 'active']] )                 ; // "{status:'active'}"
echo aqlExpression( null )                                   ; // null

This method iterates over the provided fields and applies the corresponding filter function based on the Field::FILTER option for each field. The generated expressions are then concatenated into a single string, separated by ', '.

Supported filters include:

• Scalar fields: BOOL, INT, DATETIME, DEFAULT
• Special fields: TRANSLATE, DISTANCE, REVISION
• Document relations: EDGE, EDGE_SINGLE, EDGE_COUNT, JOIN, JOIN_ARRAY, JOIN_MULTIPLE, UNIQUE_NAME

Each field can also define additional options:

• Field::NAME : The target field name in the document (optional)
• Field::UNIQUE : Unique variable name to use for the AQL expression (optional)
• Field::QUOTED : Double-quote the output label (for keys that are not bare identifiers, e.g. "my-key": …). The attribute access is then reached with backticks (doc.my-key``), the valid AQL form — never doc."my-key". A Field::NAME still overrides the source attribute (only the label is quoted).
• Field::REQUIRES : Optional permission subject(s) — when present and the request-scoped authorizer denies them, the field is dropped from the projection (read-side gating).
• Field::ALTERS : Optional alt transformation chain wrapping the projected value (e.g. ["trim","lower"] => name: LOWER(TRIM(doc.name))). Applied only to the default scalar projection (key: doc.key); ignored on typed/structural filters (BOOL, DATETIME, EDGE, JOIN, …).
• Field::NULLABLE : Optional guard on a Filter::DOCUMENT projection — the rebuilt object is emitted only when its source attribute really is an object, otherwise the field yields null (or Field::ELSE). Without it, a missing source rebuilds an object of nulls. Only valid on that filter (it throws elsewhere) — on a Filter::URL the source is a scalar key, which IS_OBJECT() never accepts; composes with Field::WHEN.
• Field::WHEN : Optional condition guarding the projected value, compiled to a ternary against the current reference and paired with Field::ELSE. Valid on the default scalar projection and on the two filters that fabricate a value with no guard of their own — Filter::DOCUMENT (an object rebuilt attribute by attribute) and Filter::URL (a link rebuilt with CONCAT(), which drops a missing key and yields a truncated address). It throws elsewhere.
• Field::SCOPE : Optional projection source — Scope::VERTEX (default) reads the field from $docRef, Scope::EDGE reads it from $edgeRef (the traversal edge). The edge scope is only valid inside an edge sub-query (where $edgeRef is provided) and only on filters that project from a reference; it throws otherwise. Scope::EDGE equals AQL::EDGE, so both forms are interchangeable.

Useful for FOR loops to prevent runtime errors when the source property is null. Transforms doc.items into (IS_ARRAY(doc.items) ? doc.items : []).

CustomRules:

• Strings are returned as-is (raw expression)
• Associative arrays => {key:value}
• Indexed arrays => [v1,v2,...]
• Objects => {key:value} using public properties
• JsonSerializable objects are jsonSerialized first

Renders the document/expression supplied under the AQL::UPDATE key as UPDATE <expression> (the expression goes through aqlExpression(), so it accepts an object literal, a [key, value] pair list, or a raw string). The AQL::UPDATE key is required: an init that omits it throws an InvalidArgumentException.

The ArangoDB syntax accepts the lookup as either a search expression or a filter expression — never both:

UPSERT [ searchExpression | FILTER filterExpression ]

Accordingly, exactly one of the two $init keys must be supplied:

• AQL::SEARCH — an object literal matched by equality, rendered as UPSERT { … } (see aqlExpression()).
• AQL::FILTER — a more flexible filter expression, rendered as UPSERT FILTER … (see aqlFilter()).

Supplying neither, or both at the same time, throws an InvalidArgumentException.

Automatically detects AQL functions using pattern matching and treats them as raw expressions. Also supports manual raw value specification for edge cases.

String handling flow:

       +--------------------------+
       |      Is $val a string?   |
       +-----------+--------------+
                   |
                  No
                   |--> return $val as-is or throw (non-string)
                   |
                  Yes
                   v
       +--------------------------+
       |   Is $val in rawValues?  |
       +-----------+--------------+
                   |
               Yes |--> return $val (raw)
                   |
                  No
                   v
       +--------------------------+
       |   Matches AQL function?  |
       | CONCAT(...), DATE_NOW()  |
       +-----------+--------------+
                   |
               Yes |--> return $val (raw)
                   |
                  No
                   v
       +--------------------------+
       | Matches AQL pattern?     |
       | doc.field, @bind, col/key|
       +-----------+--------------+
                   |
               Yes |--> return $val (raw)
                   |
                  No
                  v
       +--------------------------+
       |   Regular string         |
       |   Escape and quote       |
       |   return "'val'"         |
       +--------------------------+

The predicate itself lives in oihana/php-controllers (isLanguageCode()) — a language tag is not an ArangoDB notion. What stays here is the part that is one: deciding who to blame, below.

Who is blamed depends on where the tag came from, exactly as for an attribute name. A declared default language (Arango::DEFAULT_LANG, the site or model fallback) is the consumer's own code and no request can fix it: it refuses with a plain ValidationException, answered with a 500. A requested language (Arango::LANG, the ?lang= parameter) is told it wrote something the API cannot read — a 400.

⚠ A controller already filters ?lang= against its supported languages whitelist, so a request rarely reaches this guard. A consumer calling the model directly bypasses that controller, which is precisely why the guard lives here too.

The variable counterpart of assertAttributeName(), and not interchangeable with it: an attribute name may be a path (address.city), a variable name may not — LET address.city = … is a syntax error. Use this one before interpolating a declared identifier into a LET.

It is the query-side counterpart of stripArrayExpansion(): where the search links and the hierarchical ?filter= builder flatten the Operator::ARRAY_EXPANSION marker into a dotted path, an aggregation has to unwind it — an array element cannot be aggregated in place, it must be iterated. 'offers[*].tiers[*].amount' becomes:

FOR item  IN doc.offers
FOR item2 IN item.tiers
  … item2.amount

The path is split on the marker, every segment but the last opening one hop relative to the previous item reference, and the last segment being the projected leaf — empty for a bare tags[*], which projects the element itself. Each item reference is <itemRef>, then <itemRef>2, <itemRef>3 … (there is no <itemRef>1).

Every segment is validated by assertAttributeName() — the whole path never is, since it carries the markers — so a malformed path fails loud instead of reaching AQL. A doubled marker (a[*][*]) yields an empty intermediate container and is rejected on that ground.

The helper deliberately stops at the hops: the root FOR, the shared FILTER and the aggregation tail belong to the caller, and diverge between consumers (BoundsQueryTrait collects MIN/MAX/count, FacetCountsQueryTrait counts buckets).

Detects:

• AQL functions: CONCAT(...), DATE_NOW(), etc.
• Document references: doc.field, user.name, etc.
• Bind parameters:

This function checks if the provided expression starts with a known AQL function name (case-insensitively) followed by parentheses.

This function validates the format, not whether the document actually exists. It specifically checks for a string containing exactly one '/' separator, with characters on both sides.

A valid name is one or more identifier segments joined by dots, where each segment starts with a letter or underscore and continues with letters, digits or underscores. This is exactly what AQL dot notation accepts unquoted, so any character able to break out of an attribute path (spaces, operators, quotes, parentheses, -, ;, …) is rejected.

It is the attribute-path counterpart of isBindVariable() (which guards bind variable names): use it whenever an untrusted identifier — e.g. a facet sub-field name coming from the URL — is interpolated into a query string.

The distinction matters, and isAttributeName() is the wrong guard for this job: it validates a path, so it accepts address.city, which reads perfectly as an attribute and is a syntax error as a variable (LET address.city = …). A variable name is a single identifier: a letter or an underscore, then letters, digits and underscores.

Two failures this cannot see, because they are not about shape:

• an AQL keyword (LET, RETURN, FILTER, …) has the shape of an identifier and is refused by the server (expecting identifier);
• a name already bound in the query — doc above all — parses, then fails on execution (variable 'doc' is assigned multiple times).

Both are refused loudly by ArangoDB at the first query, with a message naming the variable, so they surface immediately rather than corrupting a result. Enumerating the keyword list here would only add a copy to keep in sync with the server, and a false sense of completeness.

Used internally by the AQL projection layer (FieldsTrait::filterFieldsBySkin) to decide whether a field declared with Field::SKINS => [...] should be projected for the current ?skin= query parameter.

Accepted shapes for $skins :

• null — no skin restriction declared, always matches
• array<string> — list of skins that activate the field, e.g. [ Skin::DEFAULT , Skin::FULL ]
• string — comma-separated list, e.g. "main,full"

String comparisons are strict and trimmed of surrounding whitespace.

Called at the point where the chain is read, never later: that is the only place where the origin is still known. The presumption is deliberate — an unmarked chain in a request slot is treated as untrusted, so forgetting to sign one gives the safe behaviour (its parameters get bound) rather than a silent hole.

• null stays null — there is no chain to qualify.
• A chain signed with trustedAlt() is unwrapped to its bare form, so it flows on exactly as it did before this mechanism existed.
• Anything else is wrapped as a request chain, which alterExpression() answers by binding its parameters — or by raising, when no binder was supplied.

Resolution order :

1. AQL::SKIN_FIELDS[$skin] — explicit projection for this skin
2. AQL::SKIN_FIELDS['*'] — fallback bucket inside SKIN_FIELDS
3. Arango::FIELDS — legacy single projection (backwards-compatible)
4. null — no projection declared at all

If AQL::SKIN_FIELDS is absent or not an array, the function ignores it and falls back directly on Arango::FIELDS — definitions that pre-date the SKIN_FIELDS feature keep their behaviour unchanged.

An upsert either inserts or writes over an existing document, and the caller usually cannot tell which from the returned document alone. WITH_STATUS answers that by leaning on AQL's own signal: on an insert there is no OLD, so the ternary reads

RETURN { doc: NEW , type: OLD ? 'replace' : 'insert' }

The write half is named by the caller, since it differs between the operations — aqlRepsert() overwrites the document (UpsertType::REPLACE) where aqlUpsert() merges into it (UpsertType::UPDATE). The insert half is always UpsertType::INSERT.

Any other AQL::RETURN value is passed through untouched, so a caller can still return a hand-written expression; the default is Clause::NEW.

ArangoSearch (Community edition) indexes the sub-fields of array elements natively when the link declares the sub-field without the [*] marker: the server descends into the array on its own. The marker is only meaningful in the AQL query (doc.contactPoints[*].email IN TOKENS(...)), never in the link definition ({ fields : { contactPoints : { fields : { email : } } } } }). This helper bridges the two surfaces by removing all the markers, so the same declared path can build the link (stripped) and the query (kept).

It is the search/link counterpart of the [*] handling already performed by the hierarchical ?filter= builder, reusing the same Operator::ARRAY_EXPANSION marker. Every marker is removed, whatever the nesting depth — a multi-level path such as employee[*].contactPoint[*].email flattens to a plain dotted path (non-correlated search; correlation would require Enterprise nested fields, out of scope here).

Only needed where a chain reaches the engine through a request slot — today $init[FilterParam::ALT], which a host may also fill programmatically through InjectFilterTrait::injectFilter(). Everything read from a model declaration (Field::ALTERS, Facet::ALT) is trusted by default and needs no signature.

Sign a chain only when it must name an expression the request could not supply — another attribute, typically. A chain carrying plain values needs nothing: bound is what you want.

Side-agnostic core shared by the key (left) and value (right) sides of a comparison: it wraps $expr — whatever it is (a field reference doc.name, a bind placeholder @value, or the loop variable CURRENT) — with the function(s) described by $chain. Used directly by the filter and facet builders (FilterTrait, FacetTrait) and by the inline-condition helpers (buildInlineFilterCondition()), so there is a single implementation.

Supports multiple syntax formats for $chain:

1. Single function: "lower" → LOWER(expr)

2. Function with params (simplified): ["substring", 0, 3] → SUBSTRING(expr, 0, 3)

3. Function chain: ["trim","lower"] → LOWER(TRIM(expr))

4. Mixed chain: ["trim",["substring",0,3],"lower"] → LOWER(SUBSTRING(TRIM(expr), 0, 3))

A name the catalogue does not carry is refused, not ignored. Every link is checked against FilterFunction before it is applied, and the refusal names the offending code — never a fragment of the query. Who wrote the chain decides which refusal: a request can fix its own URL, so it gets a ValidationException carrying 400; a model declaration cannot be fixed from the wire, so it gets an UnsupportedOperationException, which surfaces as a 500 — the consumer's code is what has to change.

⚠ One position cannot be checked, by construction. In ["trim","lowr","lower"] the second element is read as a parameter of trim — exactly as it is in the legitimate ["trim","-"] ("strip dashes"). The two notations are indistinguishable there, so a name mistyped in that position stays silent: it becomes a parameter and the rest of the chain is dropped. Write such a chain with each link nested — ["trim",["substring",0,3],"lower"] — and every link is checked again.

Given an already-resolved left operand and the (already-resolved) lower/upper bound expressions, builds the inclusive range test:

(left >= min && left <= max)   // both bounds
 left >= min                   // upper omitted (null)
 left <= max                   // lower omitted (null)

Bound omission is the CALLER's policy: pass null for a bound to drop its clause. Number/string filters drop the omitted side (one-sided range); date filters resolve an omitted bound to "now" upstream, so they never pass null. Returns an empty string when both bounds are null.

Supports multiple logic operators:

• "all": ALL conditions must be true (AND logic)
• "any": AT LEAST ONE condition must be true (OR logic)
• "none": NO condition must be true (NOT logic)

Supports two formats:

1. Simple object (all conditions are "eq" with AND logic): {"propertyID": "X", "value": true} → CURRENT.propertyID == "X" AND CURRENT.value == true

2. Explicit array with operators and logic: {"all": [ {"key": "propertyID", "op": "eq", "val": "X"}, {"key": "value", "op": "ne", "val": null} ]} → CURRENT.propertyID == "X" AND CURRENT.value != null

   {"any": [ {"key": "email", "op": "ne", "val": null}, {"key": "telephone", "op": "ne", "val": null} ]} → CURRENT.email != null OR CURRENT.telephone != null

   {"none": [ {"key": "status", "op": "eq", "val": "deleted"}, {"key": "archived", "op": "eq", "val": true} ]} → !(CURRENT.status == "deleted" OR CURRENT.archived == true)

Generates an AQL condition for use within array inline filtering syntax (CURRENT.field). Handles null values specially (no binding) and binds other values for security.

An optional $alt chain wraps the compared field (left, CURRENT.<field>) and/or the bound value (right) — same alt:{key,val} / val:true mirror vocabulary as the flat filters — so case-insensitive matches work inside the array expansion (LOWER(CURRENT.email) == LOWER(@v)).

Three backward-compatible forms are supported:

• "lower" / ["trim","lower"] (string or list) → key side only, the value is left untouched.
• { "key":<chain>, "val":<chain> } (object) → explicit chain per side.
• { "key":<chain>, "val":true } → val:true mirrors the key-side chain onto the value side.

The object form is told apart from a plain function chain by being an associative array (a list is a function chain, an associative array is the per-side object). Shared by the filter and facet builders (FilterTrait, FacetTrait) and the inline-condition helpers.

Reads the canonical Schema.org GeoCoordinates keys (latitude / longitude) first, then falls back to the short aliases (lat / lng / lon). Returns [ null, null ] when the value is not an array, or when a coordinate is missing — callers treat that as "no geo point".

The quant value answers the element axis of an array filter — « how many elements must satisfy the condition » — independently of the comparator (which lives in op). Three forms are accepted:

• a named quantifier any / all / none → ANY / ALL / NONE (resolved through FilterQuantifier::getAlias());
• a bare integer n (or its numeric string, e.g. 3 / "3") → AT LEAST (n). The threshold is cast to an int and inlined, which is injection-safe.

The returned keyword drives both array surfaces uniformly:

• scalar arrays via the array comparison operator (doc.scores ALL >= @v);
• object arrays via the question-mark operator (doc.reviews[? ALL FILTER …]).

This is the relation counterpart of resolveQuantifier() (which targets the array surface). It shares the same vocabulary — any / all / none / an integer n — but maps it to a count comparison rather than to an AQL quantifier keyword:

• any (or absent) → LENGTH(...) > 0 with a LIMIT 1 short-circuit (« at least one linked match ») — the historical, backward-compatible form;
• none → LENGTH(...) == 0 with LIMIT 1 (« no linked match »);
• all → LENGTH(...) == 0 with LIMIT 1 over the negated leaf (« no linked vertex violates the condition »); vacuously true with no relation. The caller negates the leaf and requires one to be present;
• a bare integer n (or its numeric string) → LENGTH(...) >= n, without LIMIT (the rows must be counted). The threshold is cast to an int and inlined, which is injection-safe — and consistent with the array surface.

n means « at least n » and must be >= 1: « at least 0 » is always true (use none for « no linked match »).