Oihana PHP Arango

guardProjection.php

Table of Contents

Functions

guardProjection()  : string
Wrap an already-built **fabricated** projection behind an optional guard, so the field can yield `null` (or a `Field::ELSE` fallback) instead of a value rebuilt out of nothing.

Functions

guardProjection()

Wrap an already-built **fabricated** projection behind an optional guard, so the field can yield `null` (or a `Field::ELSE` fallback) instead of a value rebuilt out of nothing.

guardProjection(string $value, array<string|int, mixed> $options, string $doc, string $source[, string|null $test = null ]) : string

Two projections fabricate rather than read, and neither fails when there is nothing to fabricate from:

  • aqlFieldDocument() reconstructs an object attribute by attribute. When the source attribute is missing, each line reads an attribute of a nothing — which AQL resolves to null without error — and the object is emitted all the same.
  • aqlFieldUrl() rebuilds a link with CONCAT(), which drops its null arguments : a missing key yields a truncated address, not a missing one.

So an empty slot comes back dressed:

{ "_key": null , "name": null , "url": "https://base/things/" }

Two markers, both opt-in, guard it:

  • Field::NULLABLE — the declared intent « nothing to build from, no value », compiled by default to an IS_OBJECT() test on $source. On a rebuilt object that is deliberately a type test and not a != null comparison: an attribute that exists but is not an object (a string, a number) rebuilds the very same object of nulls, and the house style tests the type (aqlFieldArray(), aqlFieldObject()). A caller whose shape calls for another test passes it as $test — aqlFieldBool() asks for != null, because IS_BOOL() would make every document storing 1 or "yes" abstain, when TO_BOOL() exists precisely to accept them.
  • Field::WHEN — the general mechanism, sharing the condition grammar of the scalar conditional projection (buildWhenCondition()). It is compiled against $doc, the reference the projection itself reads from — the parent of a rebuilt sub-document, and the sub-document itself for a url projected inside one: that is what keeps the read gate of conditionReadsDeniedField() correct without a line of its own, since it gates a Field::WHEN against the projection of the current level.

Declared together they compose with &&. A single condition is emitted bare, a pair between parentheses — so the guard never depends on the surrounding precedence.

With neither marker the value is returned untouched: the emitted AQL of every existing projection is unchanged, byte for byte.

Parameters
$value : string

The already-built projection value (e.g. {name:doc.thing.name}).

$options : array<string|int, mixed>

The field definition (reads NULLABLE / WHEN / ELSE).

$doc : string

The parent document reference the condition and the else branch read from.

$source : string

The source attribute the projection is rebuilt from — the sub-document for a Filter::DOCUMENT (e.g. doc.thing), the appended key for a Filter::URL (e.g. doc._key). Read by Field::NULLABLE only.

$test : string|null = null

The condition Field::NULLABLE compiles to. Defaults to IS_OBJECT($source), the test a rebuilt object calls for.

Tags
throws
UnsupportedOperationException

If the Field::WHEN descriptor is malformed.

ValidationException

If a condition or else attribute name is unsafe.

example 
guardProjection( '{name:doc.thing.name}' , [ Field::NULLABLE => true ] , 'doc' , 'doc.thing' ) ;
// IS_OBJECT(doc.thing) ? {name:doc.thing.name} : null

guardProjection( '{email:doc.contact.email}' , [ Field::WHEN => [ 'visibility' , 'public' ] ] , 'doc' , 'doc.contact' ) ;
// doc.visibility == 'public' ? {email:doc.contact.email} : null

guardProjection( "CONCAT('/things','/',doc._key)" , [ Field::WHEN => [ '_key' ] ] , 'doc' , 'doc._key' ) ;
// TO_BOOL(doc._key) ? CONCAT('/things','/',doc._key) : null

guardProjection( 'TO_BOOL(doc.active)' , [ Field::NULLABLE => true ] , 'doc' , 'doc.active' , 'doc.active != null' ) ;
// doc.active != null ? TO_BOOL(doc.active) : null
author

Marc Alcaraz (eKameleon)

since
1.6.0
Return values
string —

The value, guarded when asked for: <cond> ? <value> : <else>.

On this page

Search results