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.
- 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 (
newon insert/update/replace,oldon 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.
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:
- Collection,
- GraphVertexCollection,
- GraphEdgeCollection,
- and the bulk import / batch flows.
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
$bodyis not an array, or when the field is missing or not an array itself.
Return values
mixed —The unwrapped payload, or $fallback.