Oihana PHP Arango

GraphEdgeCollection extends GraphCollection

Read onlyYes

Edge-CRUD handle on an edge collection that belongs to a named graph.

The whole CRUD surface lives in GraphCollection; this class supplies the three things specific to edges — the /edge route segment, the edge response wrapper, and the Edge value object each response is turned into — plus the narrowed return types that keep Edge in the public signatures.

Routing through the gharial endpoint family (/_api/gharial/{graph}/edge/{collection}[/{key}]) rather than the generic document API lets the server enforce the graph's edge-definition constraints on _from / _to — inserting an edge with a _from pointing outside the allowed vertex collections fails up-front rather than silently corrupting the graph topology.

Instances are obtained through Graph::edgeCollection().

Returns typed Edge value objects (sub-class of Document exposing getFrom() / getTo()), exactly like the non-graph EdgeCollection. The gharial response wrapper ({ edge: {...} }) is unwrapped internally so callers never see it.

Example:

$graph   = $db->graph( 'workplaces' ) ;
$employs = $graph->edgeCollection( 'employs' ) ;

$edge = $employs->insert
(
    [
        '_from' => 'companies/acme' ,
        '_to'   => 'people/alice'   ,
        'since' => '2024-01-01'     ,
    ] ,
    [ 'returnNew' => true ] ,
) ;

$employs->update( $edge->getKey() , [ 'since' => '2024-06-01' ] ) ;
$employs->remove( $edge->getKey() ) ;
Tags
see
https://docs.arangodb.com/stable/develop/http-api/graphs/named-graphs/#edges
author

Marc Alcaraz (ekameleon)

since
1.0.0

Table of Contents

Constants

SUB_ROUTE  : string = '/edge'
Sub-route segment used to scope a request to the edge surface of the gharial endpoints (`/_api/gharial/{graph}/edge/...`).
WRAPPER_FIELD  : string = 'edge'
Wire field carrying the edge payload inside the gharial response wrapper.

Properties

$graph  : Graph
$name  : string

Methods

__construct()  : mixed
document()  : Edge
Fetches a single edge by key.
documentExists()  : bool
Returns true when a document with the given key exists in this collection inside the graph.
getGraph()  : Graph
Returns the parent graph this collection is bound to.
getName()  : string
Returns the collection name this instance is bound to.
insert()  : Edge
Inserts a new edge into the collection.
remove()  : Edge
Removes an edge from the collection.
replace()  : Edge
Replaces an existing edge with the given payload (PUT semantics — fields absent from `$data` are dropped, so `_from` / `_to` must be resent).
update()  : Edge
Partially updates an existing edge with the given payload (PATCH semantics — only the supplied fields are touched).
createDocument()  : Document
Builds the value object every response of this surface is turned into: a {@see Document} for a vertex collection, an {@see \oihana\arango\clients\document\Edge} for an edge one.

Constants

SUB_ROUTE

Sub-route segment used to scope a request to the edge surface of the gharial endpoints (`/_api/gharial/{graph}/edge/...`).

protected string SUB_ROUTE = '/edge'

WRAPPER_FIELD

Wire field carrying the edge payload inside the gharial response wrapper.

protected string WRAPPER_FIELD = 'edge'

Properties

Methods

__construct()

public __construct(Graph $graph, string $name) : mixed
Parameters
$graph : Graph

Parent graph.

$name : string

Name of the collection on the server.

document()

Fetches a single edge by key.

public document(string $key) : Edge
Parameters
$key : string

The edge key (_key).

Tags
throws
ArangoException

When the edge is missing or the request fails.

Return values
Edge

documentExists()

Returns true when a document with the given key exists in this collection inside the graph.

public documentExists(string $key) : bool

Uses GET /_api/gharial/{graph}/{surface}/{collection}/{key} and swallows the 404 branch. Any other failure rethrows as an ArangoException.

The GET is not an oversight, and must not be "optimized" into a HEAD. The verb costs a full document transfer for an answer one bit wide, so HEAD would be the natural choice — and it is what the non-graph Collection::documentExists() uses. The gharial endpoints do not support it: a HEAD on this route answers HTTP 500, on an existing key as well as on a missing one, for both the vertex and the edge surface. Measured against arangod, which answers 200 / 404 to the very same HEAD on the generic /_api/document route — so the limitation is the server's, not the client's. Switching would break the method outright, and no unit test would catch it: they all stub the transport and honour whatever verb they are handed.

A caller on a hot path can bypass gharial and probe the underlying collection directly ($db->collection( $name )->documentExists( $key )), which does send a HEAD — the graph constraints gharial enforces are a write-time concern and buy nothing on a read.

Parameters
$key : string

The document key.

Tags
throws
ArangoException

When the request fails for a reason other than a 404.

Return values
bool

getName()

Returns the collection name this instance is bound to.

public getName() : string
Return values
string

insert()

Inserts a new edge into the collection.

public insert(array<string, mixed> $data[, array<string, mixed> $options = [] ]) : Edge
Parameters
$data : array<string, mixed>

Edge payload (_from and _to required).

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

Server-side options (returnNew, waitForSync).

Tags
throws
ArangoException

When the request fails.

Return values
Edge

remove()

Removes an edge from the collection.

public remove(string $key[, array<string, mixed> $options = [] ]) : Edge
Parameters
$key : string

Edge key.

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

Server-side options (returnOld, waitForSync, rev).

Tags
throws
ArangoException

When the request fails.

Return values
Edge

replace()

Replaces an existing edge with the given payload (PUT semantics — fields absent from `$data` are dropped, so `_from` / `_to` must be resent).

public replace(string $key, array<string, mixed> $data[, array<string, mixed> $options = [] ]) : Edge
Parameters
$key : string

Edge key.

$data : array<string, mixed>

Replacement payload.

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

Server-side options (returnNew, returnOld, waitForSync, keepNull).

Tags
throws
ArangoException

When the request fails.

Return values
Edge

update()

Partially updates an existing edge with the given payload (PATCH semantics — only the supplied fields are touched).

public update(string $key, array<string, mixed> $partial[, array<string, mixed> $options = [] ]) : Edge
Parameters
$key : string

Edge key.

$partial : array<string, mixed>

Partial payload.

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

Server-side options (returnNew, returnOld, keepNull, waitForSync).

Tags
throws
ArangoException

When the request fails.

Return values
Edge

createDocument()

Builds the value object every response of this surface is turned into: a {@see Document} for a vertex collection, an {@see \oihana\arango\clients\document\Edge} for an edge one.

protected createDocument([array<string|int, mixed> $data = [] ]) : Document
Parameters
$data : array<string|int, mixed> = []

Decoded document attributes.

Tags
inheritDoc
Return values
Document
On this page

Search results