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)
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) and Field::NAME (document key name to append, default _key).

$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