Oihana Php Arango

EdgesGetTrait uses trait:short, trait:short

Provides edge traversal and vertex retrieval utilities for ArangoDB edge collections.

This trait defines methods to query and retrieve vertices connected through edges in an ArangoDB graph. It allows fetching all outbound vertices from a given vertex, leveraging AQL traversal patterns (OUTBOUND) to navigate relationships efficiently.

Designed to be mixed into model classes extending Documents, this trait integrates seamlessly with schema-aware document models and supports AQL bind variables, schema reflection, and container-based dependency injection.

Features

Retrieve outbound vertices (targets) connected from a given _from vertex.
Support for AQL bind variables and dynamic query compilation.
Integration with Documents models for schema-based field mapping.
Optional first-result retrieval via AQL::FIRST flag.
Safe query execution with exception handling for DI and AQL errors.

Usage

use oihana\arango\models\traits\edges\EdgesGetTrait;

class Edges extends Documents
{
    use EdgesGetTrait;
}

$edges = new Edges($container, ['collection' => 'user_follows']);

// Retrieve all outbound vertices connected from a given user
$vertices = $edges->getOutboundVertices('users/1');

// Retrieve only the first outbound vertex
$firstVertex = $edges->getOutboundVertices('users/1', [AQL::FIRST => true]);

// Example of resulting AQL query:
// FOR v IN OUTBOUND @from @@collection
// RETURN v

Notes

The _from and _to vertex identifiers must be fully qualified (e.g. 'users/1').
If $from is null, the method uses the current $this->from vertex reference.
Requires an existing edge collection and a valid ArangoDB connection in the container.
Compatible with VerticesTrait and ArangoTrait for extended AQL utilities.

Properties

$collection : string|null: The default collection name.
$indexes : array<string|int, mixed>|null: The declared indexes of the collection (the `AQL::INDEXES` list of {@see IndexOptions} or raw definitions). Retained at initialization — whether the lazy provisioning ran or not — so the declaration can be compared with the server later ({@see DoctorTrait::diagnose()}).
$arangodb : ArangoDB|null: The ArangoDB database reference.
$type : int: Indicates the type of the collection when is created (document or edge).

Methods

analyzerExists() : bool: Checks if an analyzer exists on the server (built-in analyzers are always reported).
collectionCreate() : bool: Creates a new collection if not exist.
collectionDrop() : bool: Drops a collection if exist.
collectionExists() : bool: Check if collection exists
collectionRename() : bool: Renames a collection if exist.
collectionTruncate() : bool: Truncate a collection if exist.
createIndex() : array<string|int, mixed>|null: Creates an index on a collection on the server.
debugQuery() : void: Debug the passed-in query and binds variables.
explain() : ExplainResult: Explains an AQL query — returns the optimizer's execution plan as a typed {@see ExplainResult} (rules applied, collections, estimated cost, indexes actually used) **without executing the query**.
foundRows() : int: For a SELECT with a LIMIT clause, returns the number of rows that would be returned were there no LIMIT clause.
getAnyVertices() : object|array<string|int, mixed>|null: Retrieves all vertices connected in any direction from the given vertex.
getDatabase() : ArangoDB: Returns the ArangoDB database singleton reference.
getDocuments() : array<string|int, mixed>: Prepare, execute and returns an array of all documents with the passed-in AQL query.
getExtra() : array<string|int, mixed>: Returns the AQL current extra datas.
getFirstAnyVertex() : object|array<string|int, mixed>|null: Retrieves the first vertex connected in any direction from the given vertex.
getFirstInboundVertex() : object|array<string|int, mixed>|null: Retrieves the first inbound vertex connected to the given 'to' vertex.
getFirstOutboundVertex() : object|array<string|int, mixed>|null: Retrieves the first outbound vertex connected from the given 'from' vertex.
getFirstResult() : mixed: Prepare, execute and returns the first result of the passed-in AQL query.
getInboundVertices() : object|array<string|int, mixed>|null: Retrieves all inbound vertices connected to the given 'to' vertex.
getObject() : object|null: Prepare, execute and returns an object with the passed-in AQL query.
getOutboundVertices() : object|array<string|int, mixed>|null: Retrieves all outbound vertices connected from the given 'from' vertex.
getProfile() : ProfileResult: Returns the typed profile of the last profiled query run (per-phase timings, {@see ExecutionStats}, warnings).
getResult() : object|null: Prepare, execute and returns an array with the passed-in AQL query.
getStats() : ExecutionStats: Returns the typed execution statistics of the last query (scanned / filtered / time / memory …). Most meaningful right after a profiled `list()` / `get()` (see {@see Arango::PROFILE}).
getVertices() : object|array<string|int, mixed>|null: Retrieves all vertices connected with a specific direction.
initializeCollection() : static: Sets the internal collection reference.
initializeDatabase() : static: Set the internal arangoDB reference.
initializeIndexes() : static: Sets the declared indexes of the collection from the init definition, normalizing a single {@see IndexOptions} value to a one-element list (a raw array always stays the index list) — so every consumer sees a plain `IndexOptions[]`: the {@see initializeCollection()} lazy provisioning and the {@see \oihana\arango\models\traits\DoctorTrait} diagnose/repair diffs.
initializeVertices() : static: Initialize the `from` and `to` vertices references.
prepareAndExecute() : static: Prepare and execute an ArangoDB AQL query.
prepareVertices() : string|null: Prepares the vertices "_from=xxx && _to=xxx" filter expression.
registerProperty() : void: Register a specific dynamic property in the binds and values collection to generates a query.
releaseVertices() : static: Release the 'from' and 'to' vertices references.
streamDocuments() : Generator<string|int, mixed>: Prepare, execute and returns a generator of documents with the passed-in AQL query.
viewCreate() : bool: Creates an `arangosearch` View if it does not already exist.
viewExists() : bool: Checks if a View exists.
profileOptions() : array<string|int, mixed>: Merges the cursor `profile` option into `$options` when the `$init` array requests profiling via {@see Arango::PROFILE} (`true` → profile level 2, or an explicit integer level). Returns `$options` unchanged otherwise.

$collection

The default collection name.


        public
            string|null
    $collection

$indexes

The declared indexes of the collection (the `AQL::INDEXES` list of {@see IndexOptions} or raw definitions). Retained at initialization — whether the lazy provisioning ran or not — so the declaration can be compared with the server later ({@see DoctorTrait::diagnose()}).


        public
            array<string|int, mixed>|null
    $indexes
     = null

$arangodb

The ArangoDB database reference.


        protected
            ArangoDB|null
    $arangodb
     = null

$type

Indicates the type of the collection when is created (document or edge).


        protected
            int
    $type

analyzerExists()

Checks if an analyzer exists on the server (built-in analyzers are always reported).


    public
                    analyzerExists(string $name) : bool

Parameters

$name : string: The name of the analyzer.

Return values

bool

collectionCreate()

Creates a new collection if not exist.


    public
                    collectionCreate(string $name[, array<string|int, mixed> $options = [] ]) : bool

Parameters

$name : string

The name of the new collection

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

an array of options.

Options are:

'type' - 2 -> normal collection, 3 -> edge-collection

'waitForSync' - if set to true, then all removal operations will instantly be synchronised to disk / If this is not specified, then the collection's default sync behavior will be applied.

'isSystem' - false->user collection(default), true->system collection .

'keyOptions' - key options to use.

'distributeShardsLike' - name of prototype collection for identical sharding.

'numberOfShards' - number of shards for the collection.

'replicationFactor' - number of replicas to keep (default: 1).

'writeConcern' - minimum number of replicas to be successful when writing (default: 1).

'shardKeys' - array of shard key attributes.

'shardingStrategy' - sharding strategy to use in cluster.

'smartJoinAttribute' - attribute name for smart joins (if not shard key).

'schema' - collection schema.

Return values

bool —

Returns true if the new collection is created.

collectionDrop()

Drops a collection if exist.


    public
                    collectionDrop(string $name) : bool

Parameters

$name : string: The name of the new collection

Return values

bool —

Returns true if the new collection is dropped.

collectionExists()

Check if collection exists


    public
                    collectionExists(string $name) : bool

Parameters

$name : string: The name of the collection

Return values

bool

collectionRename()

Renames a collection if exist.


    public
                    collectionRename(string $oldName, string $name) : bool

Parameters

$oldName : string: The old name of the collection
$name : string: The new name of the collection

Return values

bool —

Returns true if the collection is renamed.

collectionTruncate()

Truncate a collection if exist.


    public
                    collectionTruncate(string $name) : bool

Parameters

$name : string: The name of the collection to truncate.

Return values

bool

createIndex()

Creates an index on a collection on the server.


    public
                    createIndex(string|Collection $collection, array<string|int, mixed>|IndexOptions $indexOptions) : array<string|int, mixed>|null

Parameters

$collection : string|Collection: Collection name or Collection client handle.
$indexOptions : array<string|int, mixed>|IndexOptions: An IndexOptions definition or an associative array of options for the index like array('type' => 'persistent', 'fields' => ['id','additionalType'], 'sparse' => false)

Return values

array<string|int, mixed>|null —

The server response of the created index or null

debugQuery()

Debug the passed-in query and binds variables.


    public
                    debugQuery(string $method, string $query, array<string|int, mixed>|null $binds) : void

Parameters

$method : string
$query : string
$binds : array<string|int, mixed>|null

explain()

Explains an AQL query — returns the optimizer's execution plan as a typed {@see ExplainResult} (rules applied, collections, estimated cost, indexes actually used) **without executing the query**.


    public
                    explain(AqlQuery|string $query[, array<string, mixed> $bindVars = [] ][, array<string, mixed> $options = [] ]) : ExplainResult

Parameters

$query : AqlQuery|string: The AQL query to explain.
$bindVars : array<string, mixed> = []: Bind variables (omit when $query is an AqlQuery).
$options : array<string, mixed> = []: Explain options (allPlans, optimizer.rules, …).

Return values

ExplainResult

foundRows()

For a SELECT with a LIMIT clause, returns the number of rows that would be returned were there no LIMIT clause.


    public
                    foundRows() : int

Return values

int

getAnyVertices()

Retrieves all vertices connected in any direction from the given vertex.


    public
                    getAnyVertices([string|null $vertex = null ][, array<string|int, mixed> $init = [] ]) : object|array<string|int, mixed>|null

This method executes an AQL query to fetch vertices that are connected via incoming or outgoing edges to the specified vertex in the current edge collection. It is a convenience wrapper for getVertices() with the direction set to Traversal::ANY.

Note: By default, this method returns raw data unless an AQL::TARGET model is provided in the $init options.

Parameters

$vertex : string|null = null

Optional '_key' or '_id' of the vertex to start from. If null, defaults to the current $this->from vertex reference.

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

Optional array of query options:

AQL::ANY_REF (string) : Context for ANY traversal when using a _key (AQL::FROM or AQL::TO). Defaults to AQL::FROM.
AQL::DOC_REF (string) : AQL variable name for the vertex (default: 'vertex').
AQL::FIRST (bool) : Return only the first matched vertex.
AQL::FROM (Documents) : Override the default _from model instance.
AQL::GRAPH (string) : The name of a graph to use for traversal.
AQL::LIMIT (int) : Maximum number of vertices to return.
AQL::MAX_DEPTH (int) : Maximum traversal depth (requires AQL::GRAPH).
AQL::MIN_DEPTH (int) : Minimum traversal depth (requires AQL::GRAPH).
AQL::OFFSET (int) : Number of vertices to skip.
AQL::PRUNE (string|array) : AQL PRUNE condition for graph traversals (requires AQL::GRAPH).
AQL::RAW (bool) : Return raw array data. Defaults to true unless AQL::TARGET is specified.
AQL::RETURN (string) : Manually specify the AQL RETURN expression.
AQL::SORT (string|array) : Sorting criteria.
AQL::TARGET (Documents) : Manually specify a Document model for schema mapping.
AQL::TO (Documents) : Override the default _to model instance.
Additional bind variables can also be passed.

Tags

throws

ArangoException

If there is an error executing the AQL query.

BindException

If a bind variable is missing or invalid.

ConstantException

If the $direction argument is not a valid Traversal constant.

InvalidArgumentException

If the vertex ID is null or empty after processing.

ContainerExceptionInterface

If the DI container fails.

DependencyException

If a dependency is missing in the container.

NotFoundException

If the DI container cannot find a required service.

NotFoundExceptionInterface

Same as above, PSR-11 interface.

ReflectionException

If schema reflection fails.

Example

// $edges = Edges for 'user_follows_user'
$edges = new Edges($container, ['collection' => 'user_follows_user']);

// Get all followers and all followed users for 'users/1'
$allNeighbors = $edges->getAnyVertices('1');

Return values

object|array<string|int, mixed>|null —

Returns an array of vertex documents, a single vertex object if AQL::FIRST is true, or null if no vertices found.

getDatabase()

Returns the ArangoDB database singleton reference.


    public
                    getDatabase() : ArangoDB

Return values

ArangoDB

getDocuments()

Prepare, execute and returns an array of all documents with the passed-in AQL query.


    public
                    getDocuments(string $query[, array<string|int, mixed> $bindVars = [] ][, array<string|int, mixed> $options = [] ][, bool $raw = false ][, null|SchemaResolver|Closure|string $schema = null ]) : array<string|int, mixed>

Parameters

$query : string: The AQL query string to execute
$bindVars : array<string|int, mixed> = []: Optional bind variables for the query
$options : array<string|int, mixed> = []: Optional execution options
$raw : bool = false: If true, returns the object raw (no schema or alter applied)
$schema : null|SchemaResolver|Closure|string = null: The optional class name to map the document.

Return values

array<string|int, mixed>

getExtra()

Returns the AQL current extra datas.


    public
                    getExtra() : array<string|int, mixed>

Return values

array<string|int, mixed>

getFirstAnyVertex()

Retrieves the first vertex connected in any direction from the given vertex.


    public
                    getFirstAnyVertex([string|null $vertex = null ][, array<string|int, mixed> $init = [] ]) : object|array<string|int, mixed>|null

This is a convenience method that wraps getAnyVertices() with the AQL::FIRST flag set to true, returning only the first vertex found in the ANY traversal of the current edge collection.

It executes an AQL query equivalent to:

FOR v IN ANY @vertex @@collection RETURN v

but only returns the first resulting vertex document (if any).

Parameters

$vertex : string|null = null

Optional '_key' or '_id' of the vertex to start from. If null, defaults to the current $this->from vertex reference.

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

Optional query initialization array, merged with [AQL::FIRST => true].

AQL::ANY_REF (string) : Context for ANY traversal when using a _key (AQL::FROM or AQL::TO). Defaults to AQL::FROM.
AQL::DOC_REF (string) : AQL variable name for the vertex (default: 'vertex').
AQL::FROM (Documents) : Override the default _from model instance.
AQL::GRAPH (string) : The name of a graph to use for traversal.
AQL::LIMIT (int) : Maximum number of vertices to return.
AQL::MAX_DEPTH (int) : Maximum traversal depth (requires AQL::GRAPH).
AQL::MIN_DEPTH (int) : Minimum traversal depth (requires AQL::GRAPH).
AQL::OFFSET (int) : Number of vertices to skip.
AQL::PRUNE (string|array) : AQL PRUNE condition for graph traversals (requires AQL::GRAPH).
AQL::RAW (bool) : Return raw array data. Defaults to true unless AQL::TARGET is specified.
AQL::RETURN (string) : Manually specify the AQL RETURN expression.
AQL::SORT (string|array) : Sorting criteria.
AQL::TARGET (Documents) : Manually specify a Document model for schema mapping.
AQL::TO (Documents) : Override the default _to model instance.
Additional bind variables can also be passed.

Return values

object|array<string|int, mixed>|null —

The first vertex document connected to the given vertex, or null if no edge exists.

getFirstInboundVertex()

Retrieves the first inbound vertex connected to the given 'to' vertex.


    public
                    getFirstInboundVertex([string|null $to = null ][, array<string|int, mixed> $init = [] ]) : object|array<string|int, mixed>|null

This is a convenience method that wraps getInboundVertices() with the AQL::FIRST flag set to true, returning only the first vertex found in the inbound traversal of the current edge collection.

It executes an AQL query equivalent to:

FOR v IN INBOUND @to @@collection RETURN v

but only returns the first resulting vertex document (if any).

Parameters

$to : string|null = null

Optional '_key' or '_id' of the vertex to traverse to. If null, defaults to the current $this->to vertex reference.

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

Optional query initialization array, merged with [AQL::FIRST => true].

AQL::DOC_REF (string) : AQL variable name for the vertex (default: 'vertex').
AQL::FROM (Documents) : Override the default _from model instance.
AQL::GRAPH (string) : The name of a graph to use for traversal.
AQL::LIMIT (int) : Maximum number of vertices to return.
AQL::MAX_DEPTH (int) : Maximum traversal depth (requires AQL::GRAPH).
AQL::MIN_DEPTH (int) : Minimum traversal depth (requires AQL::GRAPH).
AQL::OFFSET (int) : Number of vertices to skip.
AQL::PRUNE (string|array) : AQL PRUNE condition for graph traversals (requires AQL::GRAPH).
AQL::RAW (bool) : Return raw array data instead of mapped objects.
AQL::RETURN (string) : Manually specify the AQL RETURN expression.
AQL::SORT (string|array) : Sorting criteria.
AQL::TARGET (Documents) : Manually specify a Document model for schema mapping.
AQL::TO (Documents) : Override the default _to model instance.
Additional bind variables can also be passed.

Tags

throws

ArangoException

If there is an error executing the AQL query.

BindException

If a bind variable is missing or invalid.

ConstantException

If the $direction argument is not a valid Traversal constant.

InvalidArgumentException

If the vertex ID is null or empty after processing.

ContainerExceptionInterface

If the DI container fails.

DependencyException

If a dependency is missing in the container.

NotFoundException

If the DI container cannot find a required service.

NotFoundExceptionInterface

Same as above, PSR-11 interface.

ReflectionException

If schema reflection fails.

Example

// $edges = Edges for 'user_follows_user'
$edges = new Edges($container, ['collection' => 'user_follows_user']);

// Retrieve the first vertex that follows 'users/1' (their first follower)
$firstFollower = $edges->getFirstInboundVertex('users/1');

Return values

object|array<string|int, mixed>|null —

The first inbound vertex document connected to the given vertex, or null if no inbound edge exists.

getFirstOutboundVertex()

Retrieves the first outbound vertex connected from the given 'from' vertex.


    public
                    getFirstOutboundVertex([string|null $from = null ][, array<string|int, mixed> $init = [] ]) : object|array<string|int, mixed>|null

This is a convenience method that wraps getOutboundVertices() with the AQL::FIRST flag set to true, returning only the first vertex found in the outbound traversal of the current edge collection.

It executes an AQL query equivalent to:

FOR v IN OUTBOUND @from @@collection RETURN v

but only returns the first resulting vertex document (if any).

Parameters

$from : string|null = null

Optional '_key' or '_id' of the vertex to start from. If null, defaults to the current $this->from vertex reference.

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

Optional query initialization array, merged with [AQL::FIRST => true].

AQL::DOC_REF (string) : AQL variable name for the vertex (default: 'vertex').
AQL::FROM (Documents) : Override the default _from model instance.
AQL::GRAPH (string) : The name of a graph to use for traversal.
AQL::LIMIT (int) : Maximum number of vertices to return.
AQL::MAX_DEPTH (int) : Maximum traversal depth (requires AQL::GRAPH).
AQL::MIN_DEPTH (int) : Minimum traversal depth (requires AQL::GRAPH).
AQL::OFFSET (int) : Number of vertices to skip.
AQL::PRUNE (string|array) : AQL PRUNE condition for graph traversals (requires AQL::GRAPH).
AQL::RAW (bool) : Return raw array data instead of mapped objects.
AQL::RETURN (string) : Manually specify the AQL RETURN expression.
AQL::SORT (string|array) : Sorting criteria.
AQL::TARGET (Documents) : Manually specify a Document model for schema mapping.
AQL::TO (Documents) : Override the default _to model instance.
Additional bind variables can also be passed.

Tags

throws

ArangoException

If there is an error executing the AQL query.

BindException

If a bind variable is missing or invalid.

ConstantException

If the $direction argument is not a valid Traversal constant.

InvalidArgumentException

If the vertex ID is null or empty after processing.

ContainerExceptionInterface

If the DI container fails.

DependencyException

If a dependency is missing in the container.

NotFoundException

If the DI container cannot find a required service.

NotFoundExceptionInterface

Same as above, PSR-11 interface.

ReflectionException

If schema reflection fails.

Example

$edges = new Edges($container, ['collection' => 'user_follows']);

// Retrieve the first vertex that 'users/1' follows
$firstVertex = $edges->getFirstOutboundVertex('users/1');

if ($firstVertex) {
echo "First followed vertex: " . $firstVertex->_id . PHP_EOL;
}

Return values

object|array<string|int, mixed>|null —

The first outbound vertex document connected from the given vertex, or null if no outbound edge exists.

getFirstResult()

Prepare, execute and returns the first result of the passed-in AQL query.


    public
                    getFirstResult(string $query[, array<string|int, mixed> $bindVars = [] ][, array<string|int, mixed> $options = [] ][, bool $raw = false ][, null|SchemaResolver|Closure|string $schema = null ]) : mixed

Parameters

$query : string: The AQL query string to execute
$bindVars : array<string|int, mixed> = []: Optional bind variables for the query
$options : array<string|int, mixed> = []: Optional execution options
$raw : bool = false: If true, returns the object raw (no schema or alter applied)
$schema : null|SchemaResolver|Closure|string = null: The optional class name to map the document.

getInboundVertices()

Retrieves all inbound vertices connected to the given 'to' vertex.


    public
                    getInboundVertices([string|null $to = null ][, array<string|int, mixed> $init = [] ]) : object|array<string|int, mixed>|null

This method executes an AQL query to fetch vertices that are connected via incoming edges to the specified vertex in the current edge collection. It is a convenience wrapper for getVertices() with the direction set to Traversal::INBOUND.

Parameters

$to : string|null = null

Optional '_key' or '_id' of the vertex to traverse to. If null, defaults to the current $this->to vertex reference.

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

Optional array of query options:

AQL::DOC_REF (string) : AQL variable name for the vertex (default: 'vertex').
AQL::FIRST (bool) : Return only the first matched vertex.
AQL::FROM (Documents) : Override the default _from model instance.
AQL::GRAPH (string) : The name of a graph to use for traversal.
AQL::LIMIT (int) : Maximum number of vertices to return.
AQL::MAX_DEPTH (int) : Maximum traversal depth (requires AQL::GRAPH).
AQL::MIN_DEPTH (int) : Minimum traversal depth (requires AQL::GRAPH).
AQL::OFFSET (int) : Number of vertices to skip.
AQL::PRUNE (string|array) : AQL PRUNE condition for graph traversals (requires AQL::GRAPH).
AQL::RAW (bool) : Return raw array data instead of mapped objects.
AQL::RETURN (string) : Manually specify the AQL RETURN expression.
AQL::SORT (string|array) : Sorting criteria.
AQL::TARGET (Documents) : Manually specify a Document model for schema mapping (overrides default $from model).
AQL::TO (Documents) : Override the default _to model instance.
Additional bind variables can also be passed.

Tags

throws

ArangoException

If there is an error executing the AQL query.

BindException

If a bind variable is missing or invalid.

ConstantException

If the $direction argument is not a valid Traversal constant.

InvalidArgumentException

If the vertex ID is null or empty after processing.

ContainerExceptionInterface

If the DI container fails.

DependencyException

If a dependency is missing in the container.

NotFoundException

If the DI container cannot find a required service.

NotFoundExceptionInterface

Same as above, PSR-11 interface.

ReflectionException

If schema reflection fails.

Example

// $edges = Edges for 'user_follows_user'
$edges = new Edges($container, ['collection' => 'user_follows_user']);

// Get all vertices that follow 'users/1' (all followers)
$followers = $edges->getInboundVertices('1');

Return values

object|array<string|int, mixed>|null —

Returns an array of vertex documents, a single vertex object if AQL::FIRST is true, or null if no vertices found.

getObject()

Prepare, execute and returns an object with the passed-in AQL query.


    public
                    getObject(string $query[, array<string|int, mixed> $bindVars = [] ][, array<string|int, mixed> $options = [] ][, bool $raw = false ][, null|SchemaResolver|Closure|string $schema = null ]) : object|null

Parameters

$query : string: The AQL query string to execute
$bindVars : array<string|int, mixed> = []: Optional bind variables for the query
$options : array<string|int, mixed> = []: Optional execution options
$raw : bool = false: If true, returns the object raw (no schema or alter applied)
$schema : null|SchemaResolver|Closure|string = null: The optional class name to map the document.

Return values

object|null

getOutboundVertices()

Retrieves all outbound vertices connected from the given 'from' vertex.


    public
                    getOutboundVertices([string|null $from = null ][, array<string|int, mixed> $init = [] ]) : object|array<string|int, mixed>|null

This method executes an AQL query to fetch vertices that are connected via outgoing edges from the specified vertex in the current edge collection. It is a convenience wrapper for getVertices() with the direction set to Traversal::OUTBOUND.

Parameters

$from : string|null = null

Optional '_key' or '_id' of the vertex to start from. If null, defaults to the current $this->from vertex reference.

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

Optional array of query options:

AQL::DOC_REF (string) : AQL variable name for the vertex (default: 'vertex').
AQL::FIRST (bool) : Return only the first matched vertex.
AQL::FROM (Documents) : Override the default _from model instance.
AQL::GRAPH (string) : The name of a graph to use for traversal.
AQL::LIMIT (int) : Maximum number of vertices to return.
AQL::MAX_DEPTH (int) : Maximum traversal depth (requires AQL::GRAPH).
AQL::MIN_DEPTH (int) : Minimum traversal depth (requires AQL::GRAPH).
AQL::OFFSET (int) : Number of vertices to skip.
AQL::PRUNE (string|array) : AQL PRUNE condition for graph traversals (requires AQL::GRAPH).
AQL::RAW (bool) : Return raw array data instead of mapped objects.
AQL::RETURN (string) : Manually specify the AQL RETURN expression.
AQL::SORT (string|array) : Sorting criteria.
AQL::TARGET (Documents) : Manually specify a Document model for schema mapping (overrides default $to model).
AQL::TO (Documents) : Override the default _to model instance.
Additional bind variables can also be passed.

Tags

throws

ArangoException

If there is an error executing the AQL query.

BindException

If a bind variable is missing or invalid.

ConstantException

If the $direction argument is not a valid Traversal constant.

InvalidArgumentException

If the vertex ID is null or empty after processing.

ContainerExceptionInterface

If the DI container fails.

DependencyException

If a dependency is missing in the container.

NotFoundException

If the DI container cannot find a required service.

NotFoundExceptionInterface

Same as above, PSR-11 interface.

ReflectionException

If schema reflection fails.

Example

$edges = new Edges($container, ['collection' => 'user_follows']);

// Get all outbound vertices from 'users/1'
$vertices = $edges->getOutboundVertices('1');

// Get only the first outbound vertex
$firstVertex = $edges->getOutboundVertices('1', [AQL::FIRST => true]);

Return values

object|array<string|int, mixed>|null —

Returns an array of vertex documents, a single vertex object if AQL::FIRST is true, or null if no vertices found.

getProfile()

Returns the typed profile of the last profiled query run (per-phase timings, {@see ExecutionStats}, warnings).


    public
                    getProfile() : ProfileResult

Return values

ProfileResult

getResult()

Prepare, execute and returns an array with the passed-in AQL query.


    public
                    getResult(string $query[, array<string|int, mixed> $bindVars = [] ][, array<string|int, mixed> $options = [] ][, bool $raw = false ][, null|SchemaResolver|Closure|string $schema = null ]) : object|null

Parameters

$query : string: The AQL query string to execute
$bindVars : array<string|int, mixed> = []: Optional bind variables for the query
$options : array<string|int, mixed> = []: Optional execution options
$raw : bool = false: If true, returns the object raw (no schema or alter applied)
$schema : null|SchemaResolver|Closure|string = null: The optional class name to map the document.

Return values

object|null

getStats()

Returns the typed execution statistics of the last query (scanned / filtered / time / memory …). Most meaningful right after a profiled `list()` / `get()` (see {@see Arango::PROFILE}).


    public
                    getStats() : ExecutionStats

Return values

ExecutionStats

getVertices()

Retrieves all vertices connected with a specific direction.


    public
                    getVertices(string $direction[, string|null $vertex = null ][, array<string|int, mixed> $init = [] ]) : object|array<string|int, mixed>|null

This method executes an AQL query to fetch vertices that are connected via edges from the specified vertex in the current edge collection. It supports standard collection traversal (FOR v IN ... @@collection) and named graph traversal (FOR v IN ... GRAPH 'graph_name').

It can optionally return only the first result, or a set of results as an array.

Parameters

$direction : string

The direction of the relation: Traversal::OUTBOUND, Traversal::INBOUND, or Traversal::ANY.

$vertex : string|null = null

Optional '_key' or '_id' of the vertex to start the relation from. If a full '_id' (e.g., "users/123") is provided, it is used directly (assumes vertexID handles this). If only a '_key' (e.g., "123") is provided, it will be prefixed based on context:

OUTBOUND: Uses the $from collection.
INBOUND: Uses the $to collection.
ANY: Uses the $from collection by default (configurable via AQL::ANY_REF).

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

Optional array of query options:

AQL::ANY_REF (string) : Context for ANY traversal when using a _key (AQL::FROM or AQL::TO). Defaults to AQL::FROM.
AQL::DOC_REF (string) : AQL variable name for the vertex (default: 'vertex').
AQL::FIRST (bool) : Return only the first matched vertex.
AQL::FROM (Documents) : Override the default _from model instance.
AQL::GRAPH (string) : The name of a graph to use for traversal (enables graph-specific options).
AQL::LIMIT (int) : Maximum number of vertices to return.
AQL::MAX_DEPTH (int) : Maximum traversal depth (requires AQL::GRAPH).
AQL::MIN_DEPTH (int) : Minimum traversal depth (requires AQL::GRAPH).
AQL::OFFSET (int) : Number of vertices to skip (for pagination).
AQL::PRUNE (string|array) : AQL PRUNE condition for graph traversals (requires AQL::GRAPH).
AQL::RAW (bool) : Return raw array data. Defaults to true for ANY traversals unless AQL::TARGET is specified.
AQL::RETURN (string) : Manually specify the AQL RETURN expression (e.g., "v.name"). Overrides model-defined returnFields.
AQL::SORT (string|array) : Sorting criteria (e.g., "vertex.name ASC"). Overrides model-defined prepareSort.
AQL::TARGET (Documents) : Manually specify a Document model for schema mapping, especially useful for ANY traversals.
AQL::TO (Documents) : Override the default _to model instance.
Additional bind variables can also be passed.

Tags

throws

ArangoException

If there is an error executing the AQL query.

BindException

If a bind variable is missing or invalid.

ConstantException

If the $direction argument is not a valid Traversal constant.

InvalidArgumentException

If the vertex ID is null or empty after processing.

ContainerExceptionInterface

If the DI container fails.

DependencyException

If a dependency is missing in the container.

NotFoundException

If the DI container cannot find a required service.

NotFoundExceptionInterface

Same as above, PSR-11 interface.

ReflectionException

If schema reflection fails.

example

Assumes $edges collection connects 'users' ($from) to 'groups' ($to)

$edges = new Edges($container, ['collection' => 'user_joins_group']);

Get all outbound vertices (groups) from 'users/1'

$vertices = $edges->getVertices( Traversal::OUTBOUND , '1' ) ;

Get only the first outbound vertex

$firstVertex = $edges->getVertices( Traversal::OUTBOUND , '1' , [AQL::FIRST => true] ) ;

Get all inbound vertices (users) from 'groups/1'

$vertices = $edges->getVertices( Traversal::INBOUND , '1' ) ;

Get all 'any' vertices from 'users/1' (works with a full _id)

$vertices = $edges->getVertices( Traversal::ANY , 'users/1' ) ;

Get 'any' vertices using _key '1'.

$vertices = $edges->getVertices( Traversal::ANY , '1' ) ;

Note : By default, it assumes '1' is a 'user' (AQL::FROM) -> 'users/1'

Force 'any' traversal to use '1' as a 'group' (AQL::TO) -> 'groups/1'

$vertices = $edges->getVertices
(
    Traversal::ANY ,
    '1' ,
    [ AQL::ANY_REF => AQL::TO ]
);

Get outbound vertices using a named graph 'my_graph'

$vertices = $edges->getVertices
(
    Traversal::OUTBOUND ,
    'users/1' ,
    [ AQL::GRAPH => 'my_graph' ]
);

Get raw outbound vertices sorted by name

$vertices = $edges->getVertices
(
    Traversal::OUTBOUND ,
    'users/1' ,
    [ AQL::RAW => true, AQL::SORT => 'vertex.name ASC' ]
);

see

PrepareTraversalTrait

Return values

object|array<string|int, mixed>|null —

Returns an array of vertex documents or a single vertex object if AQL::FIRST is true.

initializeCollection()

Sets the internal collection reference.


    public
                    initializeCollection([array<string|int, mixed> $init = [] ][, string $type = CollectionType::DOCUMENT ]) : static

Parameters

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

The options to lazy creates the collection (document or edge) or not.

collection (string) Indicates if the name of the collection.
indexes (array) The optional list of indexes to creates (if not exist and lazy).
lazy (bool) Indicates if the collection is created if not exist — resolved through LazyTrait::isLazy(), so a lazy entry defined in the DI container always wins (orchestration kill-switch), then this init key, then the property default.
options (array) The options are:
- 'waitForSync' : if set to true, then all removal operations will instantly be synchronised to disk / If this is not specified, then the collection's default sync behavior will be applied.
- 'isSystem' : false->user collection(default), true->system collection .
- 'keyOptions' : key options to use.
- 'distributeShardsLike' : name of prototype collection for identical sharding.
- 'numberOfShards' : number of shards for the collection.
- 'replicationFactor' : number of replicas to keep (default: 1).
- 'writeConcern' : minimum number of replicas to be successful when writing (default: 1).
- 'shardKeys' : array of shard key attributes.
- 'shardingStrategy' : sharding strategy to use in cluster.
- 'smartJoinAttribute' : attribute name for smart joins (if not shard key).
- 'schema' : collection schema.

$type : string = CollectionType::DOCUMENT

The default type of the collection (Default -> 'document' [2] )

Return values

static

initializeDatabase()

Set the internal arangoDB reference.


    public
                    initializeDatabase([array<string|int, mixed> $init = [] ][, ContainerInterface|null $container = null ]) : static

Parameters

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

Return values

static

initializeIndexes()

Sets the declared indexes of the collection from the init definition, normalizing a single {@see IndexOptions} value to a one-element list (a raw array always stays the index list) — so every consumer sees a plain `IndexOptions[]`: the {@see initializeCollection()} lazy provisioning and the {@see \oihana\arango\models\traits\DoctorTrait} diagnose/repair diffs.


    public
                    initializeIndexes([array<string|int, mixed> $init = [] ]) : static

Parameters

$init : array<string|int, mixed> = []: The init definition (reads the Arango::INDEXES key).

Return values

static

initializeVertices()

Initialize the `from` and `to` vertices references.


    public
                    initializeVertices([array<string|int, mixed> $init = [] ][, ContainerInterface|null $container = null ]) : static

Note: initialize too the purge reference to use in the onDeleteVertex() method.

Parameters

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

Return values

static

prepareAndExecute()

Prepare and execute an ArangoDB AQL query.


    public
                    prepareAndExecute(string $query[, array<string|int, mixed> $bindVars = [] ][, array<string|int, mixed> $options = [] ]) : static

Parameters

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

Return values

static

prepareVertices()

Prepares the vertices "_from=xxx && _to=xxx" filter expression.


    public
                    prepareVertices([string|null $from = null ][, string|null $to = null ][, array<string|int, mixed> &$binds = [] ][, array<string|int, mixed> $init = [] ]) : string|null

Parameters

$from : string|null = null

$to : string|null = null

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

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

The option of the method.

'operator' : Indicates if the filter of the vertices use a Logic::AND or Logic::OR operator (default Logic::AND)
'variableName' : The name of the document in the query (default 'doc') AQL::DOC_REF

Return values

string|null

registerProperty()


    public
                    registerProperty(string $name, mixed $value, array<string|int, mixed> &$binds, array<string|int, mixed> &$values[, string $prefix = Char::EMPTY ][, string $separator = ': ' ]) : void

Parameters

$name : string
$value : mixed
$binds : array<string|int, mixed>
$values : array<string|int, mixed>
$prefix : string = Char::EMPTY
$separator : string = ': '

releaseVertices()

Release the 'from' and 'to' vertices references.


    public
                    releaseVertices() : static

Return values

static

streamDocuments()

Prepare, execute and returns a generator of documents with the passed-in AQL query.


    public
                    streamDocuments(string $query[, array<string|int, mixed> $bindVars = [] ][, array<string|int, mixed> $options = [] ][, bool $raw = false ][, null|SchemaResolver|Closure|string $schema = null ]) : Generator<string|int, mixed>

Documents are yielded one by one, allowing efficient memory usage for large result sets.

Parameters

$query : string: The AQL query string to execute
$bindVars : array<string|int, mixed> = []: Optional bind variables for the query
$options : array<string|int, mixed> = []: Optional execution options
$raw : bool = false: If true, returns the object raw (no schema or alter applied)
$schema : null|SchemaResolver|Closure|string = null: The optional class name to map the document.

Return values

Generator<string|int, mixed> —

Generator yielding documents one by one

viewCreate()

Creates an `arangosearch` View if it does not already exist.


    public
                    viewCreate(string $name[, array<string|int, mixed> $links = [] ][, array<string|int, mixed> $options = [] ]) : bool

Parameters

$name : string: The name of the new View.
$links : array<string|int, mixed> = []: Per-collection link map (collection name → link definition).
$options : array<string|int, mixed> = []: Extra arangosearch options forwarded verbatim.

Return values

bool —

Returns true if the new View has been created.

viewExists()

Checks if a View exists.


    public
                    viewExists(string $name) : bool

Parameters

$name : string: The name of the View.

Return values

bool

profileOptions()

Merges the cursor `profile` option into `$options` when the `$init` array requests profiling via {@see Arango::PROFILE} (`true` → profile level 2, or an explicit integer level). Returns `$options` unchanged otherwise.


    protected
                    profileOptions(array<string|int, mixed> $init[, array<string|int, mixed> $options = [] ]) : array<string|int, mixed>

Parameters

$init : array<string|int, mixed>: The model input array (list() / get()).
$options : array<string|int, mixed> = []: The cursor options to augment.

Return values

array<string|int, mixed>

EdgesGetTrait uses trait:short, trait:short

Features

Usage

Notes

Tags

Table of Contents

Properties

Methods

Properties

$collection

$indexes

$arangodb

$type

Methods

analyzerExists()

Parameters

Return values

collectionCreate()

Parameters

Return values

collectionDrop()

Parameters

Return values

collectionExists()

Parameters

Return values

collectionRename()

Parameters

Tags

Return values

collectionTruncate()

Parameters

Return values

createIndex()

Parameters

Tags

Return values

debugQuery()

Parameters

explain()

Parameters

Tags

Return values

foundRows()

Return values

getAnyVertices()

Parameters

Tags

Example

Return values

getDatabase()

Return values

getDocuments()

Parameters

Tags

Return values

getExtra()

Return values

getFirstAnyVertex()

Parameters

Tags

Return values

getFirstInboundVertex()

Parameters

Tags

Example

Return values

getFirstOutboundVertex()

Parameters

Tags

Example

Return values

getFirstResult()

Parameters

Tags

getInboundVertices()

Parameters

Tags

Example

Return values