Oihana PHP Arango

edges

Table of Contents

Functions

assertEdges()  : void
Ensures that a given value is an instance of {@see Edges}.
buildEdgeCountVariable()  : string|null
Generates a string of multiple AQL 'LET' statements for calculate the number of edges of a specific document.
buildEdgeVariable()  : string
Builds a single AQL 'LET' subquery string for a specific edge relation.
buildEdgesVariables()  : string
Generates a string of multiple AQL 'LET' statements for all defined edge variables.
getEdges()  : Edges|null
Retrieves an {@see Edges} instance from various types of input definitions.
resolveEdges()  : void
Resolves and initializes internal edge model definitions from a dependency container.
sortEdgeVariable()  : string
Generates the internal AQL 'SORT' clause for an edge variable subquery.

Functions

assertEdges()

Ensures that a given value is an instance of {@see Edges}.

assertEdges(mixed $value) : void

This helper function acts as a runtime assertion to validate type safety. If the provided value is not an instance of Edges, an UnexpectedValueException is thrown with a descriptive message.

This is especially useful when handling dynamically typed data or container-resolved dependencies, where you want to enforce strict model integrity.

Parameters
$value : mixed

The value to assert as an Edges instance.

Tags
throws
UnexpectedValueException

If the provided value is not an instance of Edges.

example 
use oihana\arango\models\helpers\assertEdges;
use oihana\arango\models\Edges;

$edges = new Edges();

// ✅ Valid: no exception thrown
assertEdges( $edges );

// ❌ Invalid: throws UnexpectedValueException
assertEdges( 'not an edges instance' );
// → UnexpectedValueException: The value property must be an instance of Edges.
author

Marc Alcaraz (eKameleon)

version
1.0.0

buildEdgeCountVariable()

Generates a string of multiple AQL 'LET' statements for calculate the number of edges of a specific document.

buildEdgeCountVariable(string|null $name[, array<string|int, mixed> $definition = [] ][, string $startVertex = AQL::DOC ][, ContainerInterface|null $container = null ]) : string|null
Parameters
$name : string|null
$definition : array<string|int, mixed> = []
$startVertex : string = AQL::DOC
$container : ContainerInterface|null = null
Tags
throws
ContainerExceptionInterface
NotFoundExceptionInterface
ReflectionException
BindException
ConstantException
Return values
string|null

buildEdgeVariable()

Builds a single AQL 'LET' subquery string for a specific edge relation.

buildEdgeVariable(string|null $name[, array<string|int, mixed> $definition = [] ][, string $startVertex = AQL::DOC ][, ContainerInterface|null $container = null ][, array<string|int, mixed> $init = [] ]) : string

This method generates a complete traversal subquery, enclosed in parentheses, which is assigned to a 'LET' variable. It handles direction, filtering, sorting, and shaping of the results.

Example output: LET myFriends = ( FOR v, e IN OUTBOUND 'users/123' friends_edge ... RETURN v.name )

Parameters
$name : string|null

The logical name for this variable (e.g., 'friends', 'comments'). This is used as the AQL 'LET' variable name.

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

Configuration array for the traversal. Expected keys:

  • AQL::MODEL: (string) The class name of the Edges model.
  • AQL::DIRECTION: (string|null) Traversal direction (OUTBOUND, INBOUND).
  • AQL::UNIQUE: (string|null) Optional AQL variable name, overrides $name.
  • AQL::EDGES: (array) Further edge definitions for nested queries.
  • AQL::JOINS: (array) Join definitions for the target model.
  • AQL::SKIN: (string|null) A 'skin' name to select specific fields.
  • AQL::SORT: (string|array|null) Sort definition (see getSortEdgeVariableExpression).
$startVertex : string = AQL::DOC

The AQL variable name of the starting vertex (default 'doc').

$container : ContainerInterface|null = null

The DI Container reference.

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

Optional associative array definitions.

Tags
throws
Exception

If Traversal direction is invalid.

ContainerExceptionInterface

If the Edges model cannot be resolved from the container.

NotFoundExceptionInterface

If the Edges model cannot be resolved from the container.

ReflectionException
UnexpectedValueException

If $name is empty, the model is invalid, or the collection is not set.

Return values
string —

The complete AQL 'LET' statement.

buildEdgesVariables()

Generates a string of multiple AQL 'LET' statements for all defined edge variables.

buildEdgesVariables([array<string|int, mixed> &$variables = [] ][, array<string|int, mixed> $definitions = [] ][, string $startVertex = AQL::DOC ][, ContainerInterface|null $container = null ][, array<string|int, mixed> $init = [] ]) : string

This is a convenience method that iterates over a list of definitions and calls getEdgeVariable() for each one, concatenating the results.

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

The variables list reference to fill.

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

An associative array of edge definitions [ $name => $definition ].

$startVertex : string = AQL::DOC

The default AQL document reference (start vertex) for all traversals.

$container : ContainerInterface|null = null

The DI Container reference.

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

Optional associative array definition.

Tags
throws
ContainerExceptionInterface

| NotFoundExceptionInterface

ReflectionException
Exception
Return values
string —

A string containing all generated AQL 'LET' statements, or an empty string if none.

getEdges()

Retrieves an {@see Edges} instance from various types of input definitions.

getEdges([array<string|int, mixed>|string|Edges|null $definition = null ][, ContainerInterface|null $container = null ][, string $key = Arango::EDGES ][, Edges|null $default = null ]) : Edges|null

This helper function resolves an Edges object from a direct instance, an array definition, a service name within a PSR-11 container, or falls back to a provided default value.

Behavior:

  • If $definition is an Edges instance, it is returned as-is.
  • If $definition is an array, the function looks for the Arango::EDGES key.
  • If $definition is a non-empty string and $container contains a service with that name, the corresponding service is fetched.
  • If none of the above conditions are met, the $default value is returned.
Parameters
$definition : array<string|int, mixed>|string|Edges|null = null

Input definition that may represent an Edges instance, an associative array containing one, or a container service name.

$container : ContainerInterface|null = null

Optional PSR-11 container used to resolve string service names.

$key : string = Arango::EDGES

Array key to look for when $definition is an array

$default : Edges|null = null

Default Edges instance to return if resolution fails.

Tags
throws
ContainerExceptionInterface
NotFoundExceptionInterface
example 
use oihana\arango\models\helpers\getEdges;
use oihana\arango\models\Edges;
use oihana\arango\enums\Arango;
use Psr\Container\ContainerInterface;

$edges = new Edges(['_from' => 'users/1', '_to' => 'posts/5']);

// Example 1: Direct instance
$result = getEdges($edges);
// → returns the same $edges instance

// Example 2: From array definition
$result = getEdges([Arango::EDGES => $edges]);
// → returns the $edges instance from the array

// Example 3: From container service name
$container->method('has')->willReturn(true);
$container->method('get')->willReturn($edges);
$result = getEdges('my.edges.service', $container);
// → returns the $edges instance resolved from the container

// Example 4: With default fallback
$default = new Edges(['_from' => 'fallback/A', '_to' => 'fallback/B']);
$result = getEdges(null, null, $default);
// → returns $default
author

Marc Alcaraz (eKameleon)

version
1.0.0
Return values
Edges|null —

Returns the resolved Edges instance or the default value if not found.

resolveEdges()

Resolves and initializes internal edge model definitions from a dependency container.

resolveEdges([array<string|int, mixed>|null &$edges = [] ][, Container|null $container = null ]) : void

This helper ensures that all edge-related dependencies defined in the model configuration (under AQL::EDGES) are properly instantiated in the DI container.

It supports multiple edge definition formats:

  • Associative arrays mapping a property to its edge configuration.
  • Indexed arrays containing simple string references to container entries.
  • The special key AQL::RESOLVE (or __resolve__) for one-shot dependency resolution, used to pre-load edge models in memory without explicit configuration.

Typical usage:

resolveEdges( $model[AQL::EDGES] ?? [], $container );

Behavior:

  • Each string identifier found in indexed or AQL::RESOLVE arrays is resolved through the container.
  • Associative definitions are analyzed to resolve their AQL::MODEL entry if it refers to a container ID.
  • Existing Edges instances are left untouched.
Parameters
$edges : array<string|int, mixed>|null = []

The array of edge definitions to resolve (may be associative or indexed).

$container : Container|null = null

The DI container used to resolve Edges references.

Tags
throws
DependencyException

If a dependency cannot be loaded by the DI container.

NotFoundException

If a referenced container entry is not found.

ContainerExceptionInterface

If the container encounters a general error while resolving.

NotFoundExceptionInterface

If a referenced entry is missing in a PSR-11 container.

sortEdgeVariable()

Generates the internal AQL 'SORT' clause for an edge variable subquery.

sortEdgeVariable(array<string|int, mixed>|string|null $definition[, string $vertexRef = AQL::VERTEX ][, string $edgeRef = AQL::EDGE ][, string $defaultProperty = Schema::CREATED ]) : string

This helper method interprets a flexible sort definition and constructs the appropriate AQL 'SORT' expression.

  • If $definition is an array: Looks for AQL::SORT (property) and AQL::ORDER (ASC/DESC) and sorts by the vertex property.
  • If $definition is a string (legacy): Sorts by that string as the property on the vertex in ASC order.
  • If $definition is null (or AQL::SORT is not set in the array): Sorts by the $defaultProperty (e.g., 'created') on the edge in DESC order.
Parameters
$definition : array<string|int, mixed>|string|null

The sort configuration. Typically the $definition array from getEdgeVariable.

$vertexRef : string = AQL::VERTEX

The internal AQL vertex variable reference.

$edgeRef : string = AQL::EDGE

The internal AQL edge variable reference.

$defaultProperty : string = Schema::CREATED

The fallback property to sort by (default: 'created').

Tags
example

Assume the following constant values for the examples:

  • AQL::SORT = 'sort'
  • AQL::ORDER = 'order'
  • Order::DESC = 'DESC'
  • Order::ASC = 'ASC'
  • Schema::CREATED = 'created'
  • AQL::EDGE_PREFIX = 'e_'
  • AQL::VERTEX_PREFIX = 'v_'

Case 1: Default sort (null definition)

Sorts by 'created' on the edge (e_) in DESC order.

echo sortEdgeVariable( null , 'friends_rel');
// Output: "SORT e_friends_rel.created DESC"

Case 2: Legacy string sort (string definition)

Sorts by 'name' on the vertex (v_) in ASC order.

echo sortEdgeVariable( 'name' , 'friends_rel');
// Output: "SORT v_friends_rel.name ASC"

Case 3: Array definition (DESC)

Sorts by 'age' on the vertex (v_) in DESC order.

$definition =
[
    AQL::SORT  => 'age',
    AQL::ORDER => Order::DESC
];
echo sortEdgeVariable( $definition, 'friends_rel' );
// Output: "SORT v_friends_rel.age DESC"

Case 4: Array definition (ASC)

Sorts by 'lastName' on the vertex (v_) in ASC order.

$definition = [ AQL::SORT => 'lastName' ]; // AQL::ORDER defaults to ASC
echo sortEdgeVariable( $definition , 'friends_rel');
// Output: "SORT v_friends_rel.lastName ASC"

Case 5: Array definition missing 'sort' key ---

Falls back to default sort (Case 1).

$def5 = [ AQL::ORDER => Order::DESC ];
echo sortEdgeVariable($def5, 'friends_rel');
// Output: "SORT e_friends_rel.created DESC"
* ```
Return values
string —

The generated AQL 'SORT' clause (e.g., "SORT v_myVar_collectionName.name ASC").

On this page

Search results