Oihana Php Arango

GraphVertexCollection extends GraphCollection

Read onlyYes

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

The whole CRUD surface lives in GraphCollection; this class supplies the three things specific to vertices — the /vertex route segment, the vertex response wrapper, and the Document value object each response is turned into.

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' ) ;

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 document 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() : Document: Inserts a new document into the collection through the gharial endpoint (`POST /_api/gharial/{graph}/{surface}/{collection}`).
remove() : Document: Removes a document from the collection through the gharial endpoint.
replace() : Document: Replaces an existing document with the given payload (PUT semantics — fields absent from `$data` are dropped).
update() : Document: Partially updates an existing document 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.

SUB_ROUTE

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


    protected
        string
    SUB_ROUTE
    = '/vertex'

WRAPPER_FIELD

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


    protected
        string
    WRAPPER_FIELD
    = 'vertex'

$graph


        public
            Graph
    $graph

$name


        public
            string
    $name

__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 document by key.


    public
                    document(string $key) : Document

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

Parameters

$key : string: The document key (_key).

Return values

Document

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.

Return values

bool

getGraph()

Returns the parent graph this collection is bound to.


    public
                    getGraph() : Graph

Return values

Graph

getName()

Returns the collection name this instance is bound to.


    public
                    getName() : string

Return values

string

insert()

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


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

Parameters

$data : array<string, mixed>: Payload (_key optional; server-assigned when absent).
$options : array<string, mixed> = []: Server-side options (returnNew, waitForSync).

Return values

Document

remove()

Removes a document from the collection through the gharial endpoint.


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

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

Parameters

$key : string: Document key.
$options : array<string, mixed> = []: Server-side options (returnOld, waitForSync, rev).

Return values

Document

replace()

Replaces an existing document 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}/{surface}/{collection}/{key}.

Parameters

$key : string: Document key.
$data : array<string, mixed>: Replacement payload.
$options : array<string, mixed> = []: Server-side options (returnNew, returnOld, waitForSync, keepNull).

Return values

Document

update()

Partially updates an existing document 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}/{surface}/{collection}/{key}.

Parameters

$key : string: Document key.
$partial : array<string, mixed>: Partial payload.
$options : array<string, mixed> = []: Server-side options (returnNew, returnOld, keepNull, waitForSync).

Return values

Document

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.

Return values

Document

GraphVertexCollection extends GraphCollection

Tags

Table of Contents

Constants

Properties

Methods

Constants

SUB_ROUTE

WRAPPER_FIELD

Properties

$graph

$name

Methods

__construct()

Parameters

document()

Parameters

Tags

Return values

documentExists()

Parameters

Tags

Return values

getGraph()

Return values

getName()

Return values

insert()

Parameters

Tags

Return values

remove()

Parameters

Tags

Return values

replace()

Parameters

Tags

Return values

update()

Parameters

Tags

Return values

createDocument()

Parameters

Tags

Return values