Oihana Php Arango

aqlFieldDocument.php

Functions

aqlFieldDocument() : string: Generates an AQL key/value expression for a DOCUMENT-type field.

aqlFieldDocument()

Generates an AQL key/value expression for a DOCUMENT-type field.


    
                    aqlFieldDocument(string $key, string $doc, array<string|int, mixed> $options[, ContainerInterface|null $container = null ][, array<string|int, mixed> $init = [] ]) : string

This helper handles nested document fields and can include subfields recursively.

If $options[Field::FIELDS] is provided as an array of subfields, it generates a nested { ... } expression using aqlFields().
If no subfields are defined, it falls back to a default field expression using aqlFieldDefault().

Example usage:

// Simple document field
aqlFieldDocument('author', 'doc', ['name' => 'author']);
// Produces: "author: doc.author"

// Document field with nested subfields
aqlFieldDocument( 'author', 'doc',
[
    Field::NAME   => 'author',
    Field::FIELDS =>
    [
      'firstName' => Filter::DEFAULT ,
      'lastName'  => Filter::DEFAULT ,
    ]
]);
// Produces: "author: { firstName: doc.author.firstName, lastName: doc.author.lastName }"

Guarded projection (Field::NULLABLE / Field::WHEN):

The rebuilt object is emitted unconditionally by default — when the source attribute is missing, every line of the projection reads an attribute of a nothing, which AQL resolves to null without error, and the key comes back dressed as an object of nulls ({ _key: null, url: 'https://base/things/' }) instead of null. Two opt-in markers guard it:

Field::NULLABLE => true — the intent « no source, no object », compiled to an IS_OBJECT() test on the source attribute;
Field::WHEN — the general mechanism, the same condition grammar as a scalar conditional projection (aqlFieldConditional()), compiled against the parent reference ($doc, not the sub-document), so the permission gate of conditionReadsDeniedField() applies to it verbatim.

Both compose with &&, and the false branch is Field::ELSE (default null):

aqlFieldDocument( 'thing' , 'doc' ,
[
    Field::NULLABLE => true ,
    Field::FIELDS   => [ 'name' => [] ] ,
]);
// Produces: "thing:IS_OBJECT(doc.thing) ? {name:doc.thing.name} : null"

Without either marker the emitted AQL is unchanged, byte for byte.

Parameters

$key : string

The key of the field in the parent document.

$doc : string

The document variable or reference for the field.

$options : array<string|int, mixed>

Field options, typically including:

Field::NAME => actual key name in the document
Field::FIELDS => array of nested subfields
Field::NULLABLE => bool, guard the rebuilt object behind IS_OBJECT(<source>)
Field::WHEN => optional condition guarding the projection (parent-scoped)
Field::ELSE => the guarded projection's false branch (default null)

$container : ContainerInterface|null = null

The optional DI Container reference.

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

Optional associative array definition.

Return values

string —

AQL key/value expression representing the document field.

aqlFieldDocument.php

Table of Contents

Functions

Functions

aqlFieldDocument()

Parameters

Tags

Return values

Search results