Oihana PHP Arango

joins

Table of Contents

Functions

buildJoinVariable()  : string
Builds a single AQL 'LET' subquery string for a specific join relation.
buildJoinVariables()  : string
Generates a string of multiple AQL 'LET' statements for all defined joins variables.
sortJoinVariable()  : string
Generates the internal AQL 'SORT' clause for an edge variable subquery.

Functions

buildJoinVariable()

Builds a single AQL 'LET' subquery string for a specific join relation.

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

This method generates a complete subquery, enclosed in parentheses, which is assigned to a 'LET' variable. It handles:

  • Filtering based on the document keys or custom conditions
  • Sorting (if $isArray is true)
  • Nested edges and joins
  • Field selection and skinning

Example output:

LET myJoinVar = (
    FOR doc_join IN @@collection
        FILTER doc_join._key == doc.relatedKey
        RETURN { _key: doc_join._key, name: doc_join.name }
)
Parameters
$name : string|null

The logical name for this variable (e.g., 'friends', 'subsidiaries'). Used as the AQL 'LET' variable name.

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

Configuration array for the join. Possible keys:

  • AQL::MODEL (string) The Documents model class to query.
  • AQL::UNIQUE (string|null) Optional AQL variable name, overrides $name.
  • AQL::FIELDS (array|null) Array of fields to include in the result.
  • AQL::EDGES (array) Array of nested edge definitions.
  • AQL::JOINS (array) Array of nested join definitions.
  • AQL::SKIN (string|null) Optional 'skin' name for field selection.
  • Arango::KEY (string) The key property of the document to match (default Schema::_KEY).
  • Arango::PROPERTY (string|array|null) Optional property of the main document used as the join key.
  • Arango::SORT (string|array|null) Optional sort definition when $isArray is true.
  • Arango::CONDITIONS (callable|array|null) Optional filter conditions: - If array, it must be a list of AQL filter expressions. - If callable, it receives one or two arguments: 1. $docJoin (string) – the join document variable name 2. $docRef (string, optional) – the main document variable name - Must return an array of AQL filter expressions.
$docRef : string = AQL::DOC

The AQL variable name of the main document reference (default 'doc').

$container : ContainerInterface|null = null

Optional DI container instance used to resolve models.

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

Optional associative array used for variable initialization in nested joins.

$isArray : bool = false

If true, the join key is treated as an array of keys, generating an IN filter.

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 callable conditions closure 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 complete AQL 'LET' statement.

buildJoinVariables()

Generates a string of multiple AQL 'LET' statements for all defined joins variables.

buildJoinVariables([array<string|int, mixed> &$variables = [] ][, array<string|int, mixed> $definitions = [] ][, string $docRef = AQL::DOC ][, ContainerInterface|null $container = null ][, array<string|int, mixed> $init = [] ]) : string
Parameters
$variables : array<string|int, mixed> = []
$definitions : array<string|int, mixed> = []
$docRef : string = AQL::DOC
$container : ContainerInterface|null = null
$init : array<string|int, mixed> = []
Tags
throws
ContainerExceptionInterface
NotFoundExceptionInterface
ReflectionException
Return values
string

sortJoinVariable()

Generates the internal AQL 'SORT' clause for an edge variable subquery.

sortJoinVariable(array<string|int, mixed>|string|null $definition[, string $docRef = AQL::DOC_JOIN ][, string $defaultProperty = Schema::_KEY ]) : string

This helper method interprets a flexible sort definition and constructs the appropriate AQL 'SORT' expression.

  • If $definition is an array: Looks for AQL::SORT (property) and AQL::ORDER (ASC/DESC) and sorts by the vertex property.
  • If $definition is a string (legacy): Sorts by that string as the property on the vertex in ASC order.
  • If $definition is null (or AQL::SORT is not set in the array): Sorts by the $defaultProperty (e.g., 'created') on the edge in DESC order.
Parameters
$definition : array<string|int, mixed>|string|null

The sort configuration. Typically the $definition array from getEdgeVariable.

$docRef : string = AQL::DOC_JOIN
$defaultProperty : string = Schema::_KEY

The fallback property to sort by (default: 'created').

Tags
example

Assume the following constant values for the examples:

  • AQL::SORT = 'sort'
  • AQL::ORDER = 'order'
  • Order::DESC = 'DESC'
  • Order::ASC = 'ASC'
  • Schema::CREATED = 'created'
  • AQL::EDGE_PREFIX = 'e_'
  • AQL::VERTEX_PREFIX = 'v_'

Case 1: Default sort (null definition)

Sorts by 'created' on the edge (e_) in DESC order.

echo sortEdgeVariable( null , 'friends_rel');
// Output: "SORT e_friends_rel.created DESC"

Case 2: Legacy string sort (string definition)

Sorts by 'name' on the vertex (v_) in ASC order.

echo sortEdgeVariable( 'name' , 'friends_rel');
// Output: "SORT v_friends_rel.name ASC"

Case 3: Array definition (DESC)

Sorts by 'age' on the vertex (v_) in DESC order.

$definition =
[
    AQL::SORT  => 'age',
    AQL::ORDER => Order::DESC
];
echo sortEdgeVariable( $definition, 'friends_rel' );
// Output: "SORT v_friends_rel.age DESC"

Case 4: Array definition (ASC)

Sorts by 'lastName' on the vertex (v_) in ASC order.

$definition = [ AQL::SORT => 'lastName' ]; // AQL::ORDER defaults to ASC
echo sortEdgeVariable( $definition , 'friends_rel');
// Output: "SORT v_friends_rel.lastName ASC"

Case 5: Array definition missing 'sort' key ---

Falls back to default sort (Case 1).

$def5 = [ AQL::ORDER => Order::DESC ];
echo sortEdgeVariable($def5, 'friends_rel');
// Output: "SORT e_friends_rel.created DESC"
* ```
Return values
string —

The generated AQL 'SORT' clause (e.g., "SORT v_myVar_collectionName.name ASC").

On this page

Search results