Oihana PHP Arango

aqlFieldUrl.php

Table of Contents

Functions

aqlFieldUrl()  : string
Generates an AQL expression for a document URL field with optional dynamic placeholders.

Functions

aqlFieldUrl()

Generates an AQL expression for a document URL field with optional dynamic placeholders.

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

This function constructs a full URL for a document field by optionally combining:

  1. A base URL retrieved from a DI container (if $container and $urlKey are provided).
  2. A path pattern ($path) that can contain placeholders in the form {param} or {param:regex}.
  3. The document key (defaulting to _key or a custom $keyName).

Placeholders in the path will be replaced by values provided in the $init array under the key Arango::ARGS. If a placeholder has no corresponding value in $init, it remains unchanged in the resulting URL.

Example URL pattern:

'/observation/{observation:[A-Za-z0-9_]+}/workspace/{workspace}/places'

Example usage:

echo aqlFieldUrl(
    key       : 'url',
    options   : [ Field::PATH => '/observation/{observation}/workspace/{workspace}/places' ],
    init      : [ Arango::ARGS => ['observation' => '15454', 'workspace' => '787878'] ],
    container : $container
);
// Returns:
// url:CONCAT('https://base.url/observation/15454/workspace/787878/places','/',doc._key)

Discriminant routing (Field::PATHS):

When Field::PATHS is provided, the path is resolved at query time from a discriminant attribute of the document (default Schema::ADDITIONAL_TYPE, overridable via Field::PROPERTY) using the AQL TRANSLATE() function. Field::PATH is then mandatory and is used as the fallback route for documents whose discriminant value is not present in the map — emitting it as the third TRANSLATE() argument guarantees an unmatched value never leaks the raw discriminant into the URL.

echo aqlFieldUrl(
    key     : 'url',
    options :
    [
        Field::PATH     => '/thing' ,                                  // fallback (mandatory with PATHS)
        Field::PATHS    => [ 'Place' => '/places' , 'Person' => '/people' ] ,
        Field::PROPERTY => Schema::ADDITIONAL_TYPE ,                   // optional discriminant
    ],
    container : $container
);
// Returns:
// url:CONCAT(TRANSLATE(doc.additionalType,{Place:'https://base.url/places',Person:'https://base.url/people'},'https://base.url/thing'),'/',doc._key)

Abstaining (Field::WHEN):

AQL drops null arguments from a CONCAT(), so a document with no key does not yield a null url — it yields a truncated link leading nowhere (https://base/places/). An opt-in Field::WHEN guards the whole expression, so the field can abstain instead:

echo aqlFieldUrl(
    key     : 'url',
    options : [ Field::PATH => '/things' , Field::WHEN => [ '_key' ] ]
);
// Returns:
// url:TO_BOOL(doc._key) ? CONCAT('/things','/',doc._key) : null

The condition uses the buildWhenCondition() grammar and is compiled against $doc — the reference the projection itself reads from, which inside a sub-document projection is the sub-document. A one-element leaf ([ '_key' ]) is a truthiness test, so an absent and an empty key both abstain. Field::ELSE sets the fallback branch (default null). Without the marker the emitted AQL is unchanged, byte for byte.

Field::NULLABLE is not the marker to reach for here: it tests that the source is an object, which a document key never is. aqlFields() rejects it on every filter but Filter::DOCUMENT, and that refusal is the single seat of the rule.

Parameters
$key : string

The field key in the parent document (e.g., 'url').

$doc : string = AQL::DOC

The document reference for AQL (default: AQL::DOC).

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

The field definition. Recognised keys: Field::PATH (URL path pattern / fallback route), Field::PATHS (discriminant → route map), Field::PROPERTY (discriminant attribute, default Schema::ADDITIONAL_TYPE), Field::NAME (document key name to append, default _key) and Field::WHEN / Field::ELSE (the conditional guard, see above).

$container : ContainerInterface|null = null

Optional DI container to fetch the base URL.

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

Optional initialization array. Use Arango::ARGS to provide an associative array of placeholder values.

$urlKey : string|null = null

Optional container key for the base URL (default: Arango::BASE_URL).

Tags
throws
ValidationException

If the discriminant attribute name is unsafe.

ContainerExceptionInterface

If fetching the base URL from the container fails.

NotFoundExceptionInterface

If the container does not contain the requested base URL.

UnsupportedOperationException

If the base URL retrieved from the container is not a string, or if Field::PATHS is malformed (empty / not an associative map) or used without an explicit Field::PATH fallback.

since
1.0.0
author

Marc Alcaraz

Return values
string —

Returns an AQL snippet mapping the field to a full URL expression, e.g.: url:CONCAT('fullUrl','/',doc._key).

On this page

Search results