Oihana PHP Arango

buildJoinSubquery.php

Table of Contents

Functions

buildJoinSubquery()  : string
Builds the inner AQL join sub-query body — everything a join `LET` wraps, WITHOUT the enclosing `LET name = ( … )`.

Functions

buildJoinSubquery()

Builds the inner AQL join sub-query body — everything a join `LET` wraps, WITHOUT the enclosing `LET name = ( … )`.

buildJoinSubquery(string|null $name[, array<string|int, mixed> $definition = [] ][, string $docRef = AQL::DOC ][, ContainerInterface|null $container = null ][, array<string|int, mixed> $init = [] ][, bool $isArray = false ][, array<string|int, mixed> $extraConditions = [] ][, string|null $keyPath = null ]) : string

The returned string is the compiled body:

FOR doc_join IN collection [<nested LETs>] FILTER … [SORT …] RETURN …

buildJoinVariable() wraps it into LET name = ( … ) for a regular join, while buildPolymorphicJoinVariable() wraps several such bodies into a single APPEND( ( … ) , ( … ) ) array so the collection can vary with a discriminator field.

Extracting this body from buildJoinVariable() lets a polymorphic join reuse the whole join machinery (filtering, sorting, skinning, nested edges / joins, definition-level gating) per branch. The only addition over the historical logic is $extraConditions, a list of ready-made AQL predicates (typically the discriminator guard) prepended to the branch filter.

Arango::CONDITIONS — restricting which joined documents are kept

The definition may carry extra predicates, appended to the key match. Two shapes: a plain array of AQL predicate strings, or — the useful one — a callable returning such an array. The callable receives three arguments, always:

Arango::CONDITIONS => fn( string $join , string $parent , array $init ) :array =>
    [ $join . '.active == true' ] ,
  1. $join — the generated loop variable (a randomKey, so it cannot be hardcoded);
  2. $parent — the enclosing document reference, to compare against the parent;
  3. $init — the request-level init. Contractual keys only: Arango::AUTHORIZER, AQL::SKIN and Arango::BINDS; the rest is internal.

Declare only the parameters you need. PHP discards the surplus handed to a userland callable, so a one- or two-parameter closure keeps working untouched. An object method or an invokable is accepted too.

Returning [] emits no predicate, which is how a scope stays inert outside an HTTP request (a CLI run has no authorizer): the query is then byte-for-byte the unrestricted one, and no bind is required. A non-array return raises.

⚠️ A bind referenced as text inside a predicate (… NOT IN @hidden) cannot be discovered by the optional-bind pruning of prepareAndExecute(), which looks for aqlBindRef() objects. If a skin can drop this join, name that bind explicitly in the 4th argument of prepareAndExecute(), or ArangoDB rejects the whole query.

Parameters
$name : string|null

The logical name of the join relation — used to skin the projection and to prefix the generated variable names of nested relations. Also the default parent key path when $keyPath is null.

$definition : array<string|int, mixed> = []

Configuration array for the join — same keys as buildJoinVariable() (AQL::MODEL, AQL::FIELDS, Arango::KEY, Arango::PROPERTY, Arango::CONDITIONS, …).

$docRef : string = AQL::DOC

The AQL variable name of the main document reference.

$container : ContainerInterface|null = null

Optional DI container used to resolve models.

$init : array<string|int, mixed> = []

Optional associative array used for variable initialization.

$isArray : bool = false

If true, the join key is treated as an array of keys (IN).

$extraConditions : array<string|int, mixed> = []

Ready-made AQL predicate strings prepended to the branch filter, right after the key match (e.g. the discriminator guard of a polymorphic join).

$keyPath : string|null = null

The parent key path used to match the join, absolute from $docRef (e.g. selector.providerId → doc.selector.providerId). Null falls back on $name, keeping the historical "output name = key path" behaviour. Decoupling it from $name lets Arango::SOURCE anchor the key elsewhere and keeps nested-variable prefixes free of the (possibly dotted) key path. A polymorphic branch passes the shared key path here.

Tags
throws
Exception

If a traversal or join cannot be built properly.

ContainerExceptionInterface

If the Documents model cannot be resolved from the container.

NotFoundExceptionInterface

If the Documents model cannot be found in the container.

ReflectionException

If a nested projection or relation fails reflection.

UnexpectedValueException

If $name is empty, the model is invalid, collection not set, or CONDITIONS does not return an array.

Return values
string —

The compiled join sub-query body (no LET, no enclosing parentheses).

On this page

Search results