Oihana PHP Arango

GraphVertexCollection

Read onlyYes

Vertex-CRUD handle on a vertex collection that belongs to a named graph.

Routes every CRUD call through the gharial endpoint family (/_api/gharial/{graph}/vertex/{collection}[/{key}]) instead of the generic document API (/_api/document/...). Going through gharial lets the server enforce the graph's edge-definition constraints — inserting an edge later that points at a missing vertex, for instance, is rejected up-front.

Instances are obtained through Graph::vertexCollection().

Returns plain Document value objects, exactly like the non-graph Collection. The gharial response wrapper ({ vertex: {...} }) is unwrapped internally so callers never see it.

Example:

$graph = $db->graph( 'workplaces' ) ;
$people = $graph->vertexCollection( 'people' ) ;

$alice = $people->insert( [ '_key' => 'alice' , 'name' => 'Alice' ] , [ 'returnNew' => true ] ) ;

if ( $people->documentExists( 'alice' ) )
{
    $people->update( 'alice' , [ 'role' => 'admin' ] ) ;
}

$people->remove( 'alice' ) ;
Tags
see
https://docs.arangodb.com/stable/develop/http-api/graphs/named-graphs/#vertices
author

Marc Alcaraz (ekameleon)

since
1.0.0

Table of Contents

Constants

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

Properties

$graph  : Graph
$name  : string

Methods

__construct()  : mixed
document()  : Document
Fetches a single vertex by key.
documentExists()  : bool
Returns true when a vertex 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 vertex collection name this instance is bound to.
insert()  : Document
Inserts a new vertex into the collection through the gharial endpoint (`POST /_api/gharial/{graph}/vertex/{collection}`).
remove()  : Document
Removes a vertex from the collection through the gharial endpoint.
replace()  : Document
Replaces an existing vertex with the given payload (PUT semantics — fields absent from `$data` are dropped).
update()  : Document
Partially updates an existing vertex with the given payload (PATCH semantics — only the supplied fields are touched).
collectionPath()  : string
Builds the `/_api/gharial/{graph}/vertex/{collection}` path with both segments URL-encoded.
documentPath()  : string
Builds the `/_api/gharial/{graph}/vertex/{collection}/{key}` path with every segment URL-encoded.
unwrap()  : array<string, mixed>
Extracts the `vertex` 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()  : Document
Wraps a write-operation response body into a {@see Document}.

Constants

SUB_ROUTE

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

private string SUB_ROUTE = '/vertex'

WRAPPER_FIELD

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

private string WRAPPER_FIELD = 'vertex'

Properties

Methods

__construct()

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

Parent graph.

$name : string

Name of the vertex collection on the server.

document()

Fetches a single vertex by key.

public document(string $key) : Document

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

Parameters
$key : string

The vertex key (_key).

Tags
throws
ArangoException

When the vertex is missing or the request fails.

Return values
Document

documentExists()

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

public documentExists(string $key) : bool

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

Parameters
$key : string

The vertex key.

Tags
throws
ArangoException

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

Return values
bool

getName()

Returns the vertex collection name this instance is bound to.

public getName() : string
Return values
string

insert()

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

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

Vertex payload (_key optional; server-assigned when absent).

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

Server-side options (returnNew, waitForSync).

Tags
throws
ArangoException

When the request fails.

Return values
Document

remove()

Removes a vertex from the collection through the gharial endpoint.

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

Wraps DELETE /_api/gharial/{graph}/vertex/{collection}/{key}. Pass returnOld: true in $options to receive the deleted payload in the resulting Document.

Parameters
$key : string

Vertex key.

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

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

Tags
throws
ArangoException

When the request fails.

Return values
Document

replace()

Replaces an existing vertex with the given payload (PUT semantics — fields absent from `$data` are dropped).

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

Wraps PUT /_api/gharial/{graph}/vertex/{collection}/{key}.

Parameters
$key : string

Vertex 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
Document

update()

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

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

Wraps PATCH /_api/gharial/{graph}/vertex/{collection}/{key}.

Parameters
$key : string

Vertex 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
Document

collectionPath()

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

private collectionPath() : string
Return values
string

documentPath()

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

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

Vertex key.

Return values
string

unwrap()

Extracts the `vertex` 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 a {@see Document}.

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

The server wraps the meta document under a vertex 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) 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
Document
On this page

Search results