Oihana Php Arango

GraphCollection

Read onlyYes

AbstractYes

CRUD handle on a collection that belongs to a named graph, shared by the vertex and the edge surfaces.

Routes every call through the gharial endpoint family (/_api/gharial/{graph}/{surface}/{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 that points at a missing vertex, for instance, is rejected up-front.

The two surfaces differ by three things only, which is exactly what a subclass supplies: the route segment (GraphCollection::SUB_ROUTE), the field the server wraps the payload in (GraphCollection::WRAPPER_FIELD), and the value object each response is turned into (GraphCollection::createDocument()). Everything else — the requests, the unwrapping of the gharial envelope, the returnNew / returnOld merge, the 404 branch of the existence probe — is identical and lives here.

Instances are obtained through Graph::vertexCollection() and Graph::edgeCollection().

Constants

SUB_ROUTE : string = '': Sub-route segment scoping a request to one surface of the gharial endpoints (`/vertex` or `/edge`), supplied by the subclass.
WRAPPER_FIELD : string = '': Wire field carrying the document payload inside the gharial response wrapper (`vertex` or `edge`), supplied by the subclass.

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.
collectionPath() : string: Builds the `/_api/gharial/{graph}/{surface}/{collection}` path with both segments URL-encoded.
documentPath() : string: Builds the `/_api/gharial/{graph}/{surface}/{collection}/{key}` path with every segment URL-encoded.
unwrap() : array<string, mixed>: Extracts the surface 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 value object.

SUB_ROUTE

Sub-route segment scoping a request to one surface of the gharial endpoints (`/vertex` or `/edge`), supplied by the subclass.


    protected
        string
    SUB_ROUTE
    = ''

WRAPPER_FIELD

Wire field carrying the document payload inside the gharial response wrapper (`vertex` or `edge`), supplied by the subclass.


    protected
        string
    WRAPPER_FIELD
    = ''

$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
    abstract                createDocument([array<string, mixed> $data = [] ]) : Document

Parameters

$data : array<string, mixed> = []: Decoded document attributes.

Return values

Document

collectionPath()

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


    private
                    collectionPath() : string

Return values

string

documentPath()

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


    private
                    documentPath(string $key) : string

Parameters

$key : string: Document key.

Return values

string

unwrap()

Extracts the surface 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 value object.


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

The server wraps the meta document under the surface 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

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

Return values

collectionPath()

Return values

documentPath()

Parameters

Return values

unwrap()

Parameters

Return values

wrapWritten()

Parameters

Return values