Oihana PHP Arango

GraphEdgeCollection

Read onlyYes

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

Routes every CRUD call through the gharial endpoint family (/_api/gharial/{graph}/edge/{collection}[/{key}]) instead of the generic document API (/_api/document/...). Going through gharial 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 document 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 an edge 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 edge collection name this instance is bound to.
insert()  : Edge
Inserts a new edge into the collection through the gharial endpoint (`POST /_api/gharial/{graph}/edge/{collection}`).
remove()  : Edge
Removes an edge from the collection through the gharial endpoint.
replace()  : Edge
Replaces an existing edge with the given payload (PUT semantics — fields absent from `$data` are dropped).
update()  : Edge
Partially updates an existing edge with the given payload (PATCH semantics — only the supplied fields are touched).
collectionPath()  : string
Builds the `/_api/gharial/{graph}/edge/{collection}` path with both segments URL-encoded.
documentPath()  : string
Builds the `/_api/gharial/{graph}/edge/{collection}/{key}` path with every segment URL-encoded.
unwrap()  : array<string, mixed>
Extracts the `edge` wrapper from a gharial response body, falling back to the body itself when the wrapper is absent (defensive — the server always emits it on success).
wrapWritten()  : Edge
Wraps a write-operation response body into an {@see Edge}.

Constants

SUB_ROUTE

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

private string SUB_ROUTE = '/edge'

WRAPPER_FIELD

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

private string WRAPPER_FIELD = 'edge'

Properties

Methods

__construct()

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

Parent graph.

$name : string

Name of the edge collection on the server.

document()

Fetches a single edge by key.

public document(string $key) : Edge

Wraps GET /_api/gharial/{graph}/edge/{collection}/{key}. The server returns the document inside a {edge: {...}} envelope, which is unwrapped here.

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 an edge with the given key exists in this collection inside the graph.

public documentExists(string $key) : bool

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

Parameters
$key : string

The edge key.

Tags
throws
ArangoException

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

Return values
bool

getName()

Returns the edge collection name this instance is bound to.

public getName() : string
Return values
string

insert()

Inserts a new edge into the collection through the gharial endpoint (`POST /_api/gharial/{graph}/edge/{collection}`).

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

The payload MUST carry valid _from / _to values pointing at existing documents in one of the vertex collections the graph's edge definition allows — the server rejects mismatches with a 4xx response.

Parameters
$data : array<string, mixed>

Edge payload (_from / _to mandatory).

$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 through the gharial endpoint.

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

Wraps DELETE /_api/gharial/{graph}/edge/{collection}/{key}. Pass returnOld: true in $options to receive the deleted payload in the resulting 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).

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

Wraps PUT /_api/gharial/{graph}/edge/{collection}/{key}. The payload MUST carry valid _from / _to values; PUT semantics mean missing fields are dropped, including the endpoints — the server rejects on missing endpoints.

Parameters
$key : string

Edge key.

$data : array<string, mixed>

Replacement payload (must include _from / _to).

$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

Wraps PATCH /_api/gharial/{graph}/edge/{collection}/{key}. Useful to change metadata fields without re-stating _from / _to.

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

collectionPath()

Builds the `/_api/gharial/{graph}/edge/{collection}` path with both segments URL-encoded.

private collectionPath() : string
Return values
string

documentPath()

Builds the `/_api/gharial/{graph}/edge/{collection}/{key}` path with every segment URL-encoded.

private documentPath(string $key) : string
Parameters
$key : string

Edge key.

Return values
string

unwrap()

Extracts the `edge` wrapper from a gharial response body, falling back to the body itself when the wrapper is absent (defensive — the server always emits it on success).

private unwrap(mixed $body) : array<string, mixed>
Parameters
$body : mixed

Decoded response body.

Return values
array<string, mixed>

wrapWritten()

Wraps a write-operation response body into an {@see Edge}.

private wrapWritten(mixed $body, string $payloadField) : Edge

The server wraps the meta document under an edge key on every gharial endpoint. When the caller requested returnNew / returnOld, the payload is also present under new / old at the top level — it is merged on top of the unwrapped meta, with the meta attributes (_key / _id / _rev / _from / _to) taking precedence on key collisions.

Parameters
$body : mixed

Decoded response body.

$payloadField : string

Payload field name (new for insert/replace/update, old for remove).

Return values
Edge
On this page

Search results