Oihana PHP Arango

helpers

Table of Contents

Functions

mergeWrittenPayload()  : array<string, mixed>
Merges the optional `new` / `old` payload returned by an ArangoDB write endpoint into the meta document, so the caller sees a single flat array regardless of whether `returnNew` / `returnOld` was set.
probeExists()  : bool
Turns a server request into an existence answer: `true` when it succeeds, `false` on a 404, and the original failure for anything else.
stringifyOptions()  : array<string, mixed>
Coerces boolean entries of a server-options array to the lowercase `"true"` / `"false"` spelling ArangoDB expects when these options travel on the query string of a request.
unwrapField()  : mixed
Extracts a single wrapper field from a server response body, with a typed fallback when the field is missing or the body itself is not an array.

Functions

mergeWrittenPayload()

Merges the optional `new` / `old` payload returned by an ArangoDB write endpoint into the meta document, so the caller sees a single flat array regardless of whether `returnNew` / `returnOld` was set.

mergeWrittenPayload(array<string, mixed> $body, string $payloadField) : array<string, mixed>

On an insert / update / replace call with returnNew: true, the server responds with:

{ "_key" : "..." , "_id" : "..." , "_rev" : "..." , "new" : { ... full document ... } }

The wire convention is that the meta attributes (_key / _id / _rev, and for edges _from / _to) take precedence over the payload — even when _rev is duplicated in both, the outer copy is the authoritative one. This helper applies that precedence and strips the now-redundant payload field from the result.

When the payload field is absent (the caller did not request returnNew / returnOld), $body is returned untouched.

Pure function — used by Collection write paths and by the gharial vertex/edge write paths.

Parameters
$body : array<string, mixed>

Full response body carrying the meta attributes at the top level and (optionally) the payload under $payloadField.

$payloadField : string

Name of the optional payload field (new on insert/update/replace, old on remove).

Return values
array<string, mixed> —

The meta merged with the payload (meta wins on key collisions), with the payload field stripped. When the payload is absent, $body is returned unchanged.

probeExists()

Turns a server request into an existence answer: `true` when it succeeds, `false` on a 404, and the original failure for anything else.

probeExists(callable $request) : bool

Every resource handle of the client answers the same question the same way — Analyzer::exists(), View::exists(), Graph::exists(), Transaction::exists(), Collection::exists() and the two documentExists() of Collection and GraphCollection. Only the request differs (the verb, the path, and which handle carries the transport), which is why it travels as a closure rather than as parameters.

A 404 is the only failure read as an answer. The net is HttpException — the type the response factory produces for an ordinary HTTP status — and deliberately not its parent ArangoException: the sibling classes ConflictException (409), MaintenanceException (503) and NetworkException (0) describe a server that could not answer, not a resource that is missing, and must reach the caller untouched.

Parameters
$request : callable

The request to run; its return value is discarded.

Tags
throws
ArangoException

Any failure other than a 404, unchanged.

example 
use function oihana\arango\clients\helpers\probeExists;

public function exists() : bool
{
    return probeExists( fn() => $this->database->request( method : HttpMethod::GET , path : $this->path() ) ) ;
}
since
1.6.0
author

Marc Alcaraz

Return values
bool —

true when the request succeeds, false on a 404.

stringifyOptions()

Coerces boolean entries of a server-options array to the lowercase `"true"` / `"false"` spelling ArangoDB expects when these options travel on the query string of a request.

stringifyOptions(array<string, mixed> $options) : array<string, mixed>

Non-boolean values are forwarded as-is. Integer, float and string options keep their wire shape; only the booleans are normalised, because Guzzle would otherwise serialise PHP true / false as "1" / "" — which ArangoDB rejects.

Pure function (no state, no side effects). Used by every surface of the client that forwards a per-call options array as query parameters:

Parameters
$options : array<string, mixed>
Return values
array<string, mixed>

unwrapField()

Extracts a single wrapper field from a server response body, with a typed fallback when the field is missing or the body itself is not an array.

unwrapField(mixed $body, string $field[, mixed $fallback = null ]) : mixed

ArangoDB consistently wraps payloads inside an envelope on its /_api/gharial/* and /_api/transaction/* endpoints:

{ "graph"  : { ... } }      // GET /_api/gharial/{name}
{ "vertex" : { ... } }      // GET /_api/gharial/{g}/vertex/{c}/{k}
{ "edge"   : { ... } }      // GET /_api/gharial/{g}/edge/{c}/{k}
{ "result" : { ... } }      // GET /_api/transaction/{id}

unwrapField() reads that wrapper and returns the inner payload (or $fallback when the wrapper is absent / malformed). Pure function — no side effects, defensive against partial responses.

Parameters
$body : mixed

Decoded response body.

$field : string

Name of the wrapper field to extract.

$fallback : mixed = null

Value to return when $body is not an array, or when the field is missing or not an array itself.

Return values
mixed —

The unwrapped payload, or $fallback.

On this page

Search results