Oihana PHP Arango

buildPolymorphicRelationVariable.php

Table of Contents

Functions

buildPolymorphicRelationVariable()  : string
Assembles the AQL 'LET' of a *polymorphic* relation — a join or an edge whose target collection is chosen at query time from a discriminator field — shared by {@see \oihana\arango\models\helpers\joins\buildPolymorphicJoinVariable()} and {@see \oihana\arango\models\helpers\edges\buildPolymorphicEdgeVariable()}.

Functions

buildPolymorphicRelationVariable()

Assembles the AQL 'LET' of a *polymorphic* relation — a join or an edge whose target collection is chosen at query time from a discriminator field — shared by {@see \oihana\arango\models\helpers\joins\buildPolymorphicJoinVariable()} and {@see \oihana\arango\models\helpers\edges\buildPolymorphicEdgeVariable()}.

buildPolymorphicRelationVariable(string|null $name, array<string|int, mixed> $definition, string $ref, array<string|int, mixed> $init, callable $buildBranch) : string

AQL forbids a computed collection in FOR … IN …, so the relation is compiled as an APPEND of guarded static branches: one sub-query per Arango::MAP entry, each guarded by an equality on the discriminator so only the matching branch yields rows. The $buildBranch callback is the only relation-specific part — it turns a branch definition + its guard into a parenthesized sub-query string (a join wraps buildJoinSubquery(), an edge delegates to the already-parenthesized buildEdgeSubquery()).

Security (fail-closed):

  • Per-branch gate — a branch denied by isAuthorized() (Field::REQUIRES / AQL::REQUIRES) is dropped from the APPEND; its collection is never queried, so neither a value nor an existence bit of the hidden type leaks.
  • Fallback — an optional Arango::FALLBACK branch catches discriminator values matching none of the DECLARED types, guarded by NOT IN [ … ] over all map keys (gated or not), so a document of a denied type routes to nothing, never to the fallback (no oracle).
  • When every branch is dropped the LET holds [], so the projection resolves to null / [] rather than a broken statement.
Parameters
$name : string|null

The relation field name (also the default LET variable name).

$definition : array<string|int, mixed>

The polymorphic definition. Keys:

  • Arango::DISCRIMINATOR (string) Parent / start-vertex field deciding the branch (required).
  • Arango::MAP (array) Non-empty type => relation-definition table (required).
  • Arango::UNIQUE (string|null) Optional LET variable name, overrides $name.
  • Arango::FALLBACK (array|null) Definition for unmatched discriminator values (null = none).
$ref : string

The AQL variable name carrying the discriminator (docRef for a join, the start vertex for an edge).

$init : array<string|int, mixed>

The request-level init array (reads Arango::AUTHORIZER).

$buildBranch : callable

fn(array $branch, string $guard): string — builds one parenthesized, guarded branch sub-query. Called only on array branches that pass the gate.

Tags
throws
UnexpectedValueException

If $name is empty, Arango::MAP / Arango::DISCRIMINATOR is missing or invalid, a map branch is not an array, or Arango::FALLBACK is a non-array, non-null value.

since
1.0.0
author

Marc Alcaraz

Return values
string —

The complete AQL 'LET' statement.

On this page

Search results