EdgesInsertTrait uses trait:short, trait:short, trait:short, trait:short
Provides edge insertion utilities for ArangoDB edge collections.
This trait simplifies the process of inserting edge documents, handling vertex ID resolution and optional uniqueness checks before insertion.
It is designed to be mixed into model classes extending Documents that represent an edge collection and also utilize:
- DocumentsInsertTrait (for the base
insert()method) - EdgesExistTrait (for the
existEdge()method used in uniqueness checks) - VerticesTrait (for
vertexID()helper andfrom/tomodel contexts) - ArangoTrait (for query execution)
Features
- Resolves
_fromand_tovertex keys/IDs using context models. - Optionally checks for pre-existing edges between the same vertices before inserting.
- Throws a specific exception (
Error409) if a duplicate is found and uniqueness is enforced. - Delegates the actual insertion to the robust
insert()method.
Tags
Table of Contents
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.
- existEdge() : bool
- Checks if an edge exists between the given '_from' and '_to' vertices.
- existEdgeFrom() : bool
- Checks if at least one edge exists from the specified 'from' vertex.
- existEdgeTo() : bool
- Checks if at least one edge exists to the specified 'to' vertex.
- 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.
- 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.
- getFirstResult() : mixed
- Prepare, execute and returns the first result of the passed-in AQL query.
- getObject() : object|null
- Prepare, execute and returns an object with the passed-in AQL query.
- 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}).
- hasAnyVertex() : bool
- Checks if a specific target vertex is a neighbor in any direction.
- hasInboundVertex() : bool
- Checks if a specific target vertex is an inbound neighbor of the start vertex.
- hasOutboundVertex() : bool
- Checks if a specific target vertex is an outbound neighbor of the start vertex.
- 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.
- insert() : object|null
- Insert a new document into the collection.
- insertEdge() : object|null
- Inserts a new edge document connecting two vertices, optionally checking for uniqueness.
- 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.
- hasVertex() : bool
- Private helper to check for vertex existence in a specific direction.
Properties
$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
Methods
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
boolcollectionCreate()
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
boolcollectionRename()
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
Tags
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
boolcreateIndex()
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)
Tags
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
existEdge()
Checks if an edge exists between the given '_from' and '_to' vertices.
public
existEdge([string|null $from = null ][, string|null $to = null ][, array<string|int, mixed> $init = [] ]) : bool
Parameters
- $from : string|null = null
-
Optional 'from' vertex unique key identifier.
- $to : string|null = null
-
Optional 'to' vertex unique key identifier.
- $init : array<string|int, mixed> = []
-
Optional query options, e.g., bind variables.
Tags
Return values
bool —True if at least one edge exists, false otherwise.
existEdgeFrom()
Checks if at least one edge exists from the specified 'from' vertex.
public
existEdgeFrom(string $from[, array<string|int, mixed> $init = [] ]) : bool
Parameters
- $from : string
-
The 'from' vertex unique key identifier.
- $init : array<string|int, mixed> = []
-
Optional query options.
Tags
Return values
bool —True if at least one edge exists, false otherwise.
existEdgeTo()
Checks if at least one edge exists to the specified 'to' vertex.
public
existEdgeTo(string $to[, array<string|int, mixed> $init = [] ]) : bool
Parameters
- $to : string
-
The 'to' vertex unique key identifier.
- $init : array<string|int, mixed> = []
-
Optional query options.
Tags
Return values
bool —True if at least one edge exists, false otherwise.
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
$queryis an AqlQuery). - $options : array<string, mixed> = []
-
Explain options (
allPlans,optimizer.rules, …).
Tags
Return values
ExplainResultfoundRows()
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
intgetDatabase()
Returns the ArangoDB database singleton reference.
public
getDatabase() : ArangoDB
Return values
ArangoDBgetDocuments()
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.
Tags
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>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.
Tags
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.
Tags
Return values
object|nullgetProfile()
Returns the typed profile of the last profiled query run (per-phase timings, {@see ExecutionStats}, warnings).
public
getProfile() : ProfileResult
Return values
ProfileResultgetResult()
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.
Tags
Return values
object|nullgetStats()
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
ExecutionStatshasAnyVertex()
Checks if a specific target vertex is a neighbor in any direction.
public
hasAnyVertex(string $source, string $target[, array<string|int, mixed> $init = [] ]) : bool
Parameters
- $source : string
-
The '_key' or '_id' of the vertex to start from.
- $target : string
-
The '_key' or '_id' of the target vertex to check for.
- $init : array<string|int, mixed> = []
-
Optional array of query options (e.g.,
AQL::GRAPH).
Tags
Return values
bool —True if the target vertex is a neighbor, false otherwise.
hasInboundVertex()
Checks if a specific target vertex is an inbound neighbor of the start vertex.
public
hasInboundVertex(string $to, string $from[, array<string|int, mixed> $init = [] ]) : bool
Parameters
- $to : string
-
The '_key' or '_id' of the vertex to traverse to (start vertex).
- $from : string
-
The '_key' or '_id' of the target vertex to check for.
- $init : array<string|int, mixed> = []
-
Optional array of query options (e.g.,
AQL::GRAPH).
Tags
Return values
bool —True if the target vertex is an inbound neighbor, false otherwise.
hasOutboundVertex()
Checks if a specific target vertex is an outbound neighbor of the start vertex.
public
hasOutboundVertex(string $from, string $to[, array<string|int, mixed> $init = [] ]) : bool
Parameters
- $from : string
-
The '_key' or '_id' of the vertex to start from.
- $to : string
-
The '_key' or '_id' of the target vertex to check for.
- $init : array<string|int, mixed> = []
-
Optional array of query options (e.g.,
AQL::GRAPH).
Tags
Return values
bool —True if the target vertex is an outbound neighbor, false otherwise.
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
lazyentry 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] )
Tags
Return values
staticinitializeDatabase()
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
Tags
Return values
staticinitializeIndexes()
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::INDEXESkey).
Return values
staticinitializeVertices()
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
Tags
Return values
staticinsert()
Insert a new document into the collection.
public
insert([array{binds?: array|null, conditions?: array|null, debug?: bool|null, doc?: null|array|object|string, excludes?: array|null} $init = [] ]) : object|null
Parameters
- $init : array{binds?: array|null, conditions?: array|null, debug?: bool|null, doc?: null|array|object|string, excludes?: array|null} = []
-
The parameters to passed-in the function.
- doc : The document to insert in the collection.
- excludes : The list of all attributes to excludes in the new document
- binds The default variables to binds.
- relations The edges relations definitions to link after the insertion
Tags
Return values
object|nullinsertEdge()
Inserts a new edge document connecting two vertices, optionally checking for uniqueness.
public
insertEdge(string $from, string $to[, array<string|int, mixed> $doc = [] ][, array<string|int, mixed> $init = [] ]) : object|null
Constructs the edge document (_from, _to, attributes) and delegates
to the generic insert() method. By default, it first checks if an edge
with the same _from and _to already exists using existEdge() and throws
an Error409 if found. This behavior can be disabled via the AQL::UNIQUE option.
Parameters
- $from : string
-
The
_keyor full_idof the source vertex. Resolved using$this->fromcontext if only a key is given. - $to : string
-
The
_keyor full_idof the target vertex. Resolved using$this->tocontext if only a key is given. - $doc : array<string|int, mixed> = []
-
Optional additional document to complete the edge document (e.g.,
['createdAt' => time()]). - $init : array<string|int, mixed> = []
-
Optional array for query options:
- AQL::UNIQUE (bool) : If
true(default), checks for an existing edge between$fromand$tobefore inserting. ThrowsError409if found. Iffalse, attempts direct insert (faster, relies on DB index or allows duplicates). - AQL::OPTIONS (array): Options passed to the underlying ArangoDB
INSERToperation (see InsertOptions). - Other options accepted by the underlying
insert()method (e.g.,AQL::EXCLUDES).
- AQL::UNIQUE (bool) : If
Tags
Return values
object|null —The newly inserted edge document object , or null on failure.
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> = []
Tags
Return values
staticprepareVertices()
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
Tags
Return values
string|nullregisterProperty()
Register a specific dynamic property in the binds and values collection to generates a query.
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
staticstreamDocuments()
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.
Tags
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
boolprofileOptions()
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>hasVertex()
Private helper to check for vertex existence in a specific direction.
private
hasVertex(string $direction, string $startVertex, string $targetVertex[, array<string|int, mixed> $init = [] ]) : bool
This method builds the filter query to check if a $targetVertex exists in the results of a traversal from $startVertex.
Parameters
- $direction : string
-
Traversal::OUTBOUND, Traversal::INBOUND, or Traversal::ANY
- $startVertex : string
-
The _key or _id of the vertex to start from.
- $targetVertex : string
-
The _key or _id of the vertex to find.
- $init : array<string|int, mixed> = []
-
Optional query options.