Oihana PHP Arango

helpers

Table of Contents

Functions

ascKey()  : string
Returns the ascending form of a sort key in the textual sort grammar (the same grammar consumed by `SortTrait::prepareSort` and the HTTP `?sort=` query parameter).
decodeRevision()  : array<string|int, mixed>|null
Decompose the specified revision string into its components.
descKey()  : string
Returns the descending form of a sort key in the textual sort grammar (the same grammar consumed by `SortTrait::prepareSort` and the HTTP `?sort=` query parameter).
encodeRevision()  : string
Encodes a date into an ArangoDB `_rev` (revision) string.
parseCollection()  : string|null
Returns the collection name portion of an ArangoDB document handle (`<collection>/<key>`).
parseIdentifier()  : array{collection: string|null, key: string|null}|null
Parses an ArangoDB document handle (`<collection>/<key>`) into its components.
parseKey()  : string|null
Returns the `_key` portion of an ArangoDB document handle (`<collection>/<key>`).
sortKeys()  : string
Composes a comma-separated sort expression in the textual sort grammar (the same grammar consumed by `SortTrait::prepareSort` and the HTTP `?sort=` query parameter).

Functions

ascKey()

Returns the ascending form of a sort key in the textual sort grammar (the same grammar consumed by `SortTrait::prepareSort` and the HTTP `?sort=` query parameter).

ascKey(string $key) : string

The ascending form is the key itself — no leading -. The helper exists for symmetry with descKey() and to make sort intent explicit at call site, avoiding magic-string concatenations.

Do not confuse with aqlAsc(), which builds the AQL output token ("doc.name ASC") — this helper produces the HTTP/textual input token ("name").

Parameters
$key : string

The sort field (typically a typed constant such as Prop::CREATED).

Tags
example 
use App\Enums\Prop;
use oihana\arango\enums\Arango;

use function oihana\arango\helpers\ascKey;
use function oihana\arango\helpers\sortKeys;

Arango::SORT => ascKey( Prop::NAME ) ;                          // 'name'
Arango::SORT => sortKeys( descKey( Prop::CREATED ) , ascKey( Prop::NAME ) ) ;
see
descKey()

Descending counterpart.

sortKeys()

Joins multiple sort tokens with a comma.

author

Marc Alcaraz

Return values
string —

The ascending sort token.

decodeRevision()

Decompose the specified revision string into its components.

decodeRevision(string|null $revision[, bool $throwable = false ]) : array<string|int, mixed>|null

The resulting object has a date and a count attribute. This function is supposed to be called with the _rev attribute value of a database document as argument.

Decodes an ArangoDB revision string (_rev) into a timestamp and a counter.

This function implements the C++ algorithm used by ArangoDB to decode the _rev string into a 64-bit integer, then splits it into a timestamp (milliseconds since epoch) and a counter. The result is returned as an associative array with 'date' (ISO 8601 format) and 'count' (integer).

Parameters
$revision : string|null

The ArangoDB revision string (e.g., "jGPSg12---"). Must be 10 or 11 characters long, start with '', and contain at least one letter.

$throwable : bool = false

If true, throws exceptions on error. If false, returns null on error.

Tags
throws
InvalidArgumentException

If $revision is null or empty and $throwable is true.

RuntimeException

If $revision is invalid (wrong length, format, or content) and $throwable is true, or if the GMP extension is not loaded and $throwable is true.

example

Example usage:

$revision = '_jGPSg12---';
$result = decodeRevision($revision);
// $result = ['date' => '2025-01-20T15:28:40.830Z', 'count' => 0]

Example with invalid revision (returns null or throws exception):

$result = decodeRevision('_1234567890', true); // Throws RuntimeException
$result = decodeRevision('_1234567890');      // Returns null
see
https://docs.arangodb.com/3.11/aql/functions/miscellaneous/#decode_rev
encodeRevision()

For encoding a _rev string with a specific date and an optional count value.

author

Marc Alcaraz (eKameleon)

version
1.0.0
Return values
array<string|int, mixed>|null —

Returns an associative array with 'date' and 'count' keys on success, or null on failure. Example return value: ['date' => '2025-01-20T15:28:40.830Z', 'count' => 0]. Returns null if the input is invalid or if the GMP extension is not loaded.

descKey()

Returns the descending form of a sort key in the textual sort grammar (the same grammar consumed by `SortTrait::prepareSort` and the HTTP `?sort=` query parameter).

descKey(string $key) : string

The descending form is the key prefixed with -. This helper centralizes that convention, avoiding magic-string concatenations like '-' . Prop::CREATED.

Do not confuse with aqlDesc(), which builds the AQL output token ("doc.name DESC") — this helper produces the HTTP/textual input token ("-name").

Parameters
$key : string

The sort field (typically a typed constant such as Prop::CREATED).

Tags
example 
use App\Enums\Prop;
use oihana\arango\db\enums\AQL;
use oihana\arango\enums\Arango;

use function oihana\arango\helpers\descKey;
use function oihana\arango\helpers\sortKeys;

AQL::SORT_DEFAULT => descKey( Prop::CREATED ) ;                            // '-created'
Arango::SORT      => descKey( Prop::CREATED ) ;                            // '-created'
Arango::SORT      => sortKeys( descKey( Prop::CREATED ) , Prop::NAME ) ;   // '-created,name'
Arango::SORT      => sortKeys( descKey( Prop::CREATED ) , descKey( Prop::NAME ) ) ; // '-created,-name'
see
ascKey()

Ascending counterpart.

sortKeys()

Joins multiple sort tokens with a comma.

author

Marc Alcaraz

Return values
string —

The descending sort token, prefixed with -.

encodeRevision()

Encodes a date into an ArangoDB `_rev` (revision) string.

encodeRevision(string $date[, int|null $count = null ][, bool $throwable = false ]) : string

This function is the inverse of decodeRevision(). It generates a 10–11 character _rev string from a given date and an optional counter (count). The _rev string encodes a 64-bit integer composed of:

  1. A 44-bit timestamp in milliseconds since epoch (UTC).
  2. A 20-bit counter (count) to ensure uniqueness for multiple revisions at the same millisecond.

If $count is null, the function automatically increments the counter for multiple calls within the same millisecond, mimicking ArangoDB's internal behavior.

Parameters
$date : string

The date to encode, in any format accepted by DateTimeImmutable. Must be UTC or will be converted to UTC.

$count : int|null = null

Optional counter for revisions within the same millisecond. If null, automatically incremented for multiple calls in the same millisecond. Must be between 0 and 1048575 (2^20 - 1).

$throwable : bool = false

If true, throws exceptions on error; if false, returns an empty string.

Tags
throws
RuntimeException

If the GMP extension is not loaded and $throwable is true.

InvalidArgumentException

If the date is invalid or $count is out of range and $throwable is true.

example

Example usage with explicit count:

$date = '2025-01-20T15:28:40.830Z';
$count = 0;
$rev = encodeRevision($date, $count);
echo $rev; // e.g. "_jGPSg12---"

Example usage with automatic count:

$date = '2025-10-25T12:00:00.000Z';
$rev1 = encodeRevision($date);
$rev2 = encodeRevision($date); // automatically increments count
$rev3 = encodeRevision($date); // increments again
see
https://docs.arangodb.com/3.11/aql/functions/miscellaneous/#decode_rev
decodeRevision()

For decoding a _rev string back to date and count.

author

Marc Alcaraz (eKameleon)

version
1.0.0
Return values
string —

Returns the encoded _rev string (10–11 characters). Returns an empty string on error if $throwable is false.

parseCollection()

Returns the collection name portion of an ArangoDB document handle (`<collection>/<key>`).

parseCollection(string|null $id) : string|null

PHP mirror of the AQL function PARSE_COLLECTION. Returns null when the input has no / separator (a bare _key is not a valid handle and has no collection to extract).

Parameters
$id : string|null

The full document handle (e.g. "users/abc123").

Tags
example 
parseCollection( 'users/abc123' ) ; // 'users'
parseCollection( 'roles/42' )     ; // 'roles'
parseCollection( 'just-a-key' )   ; // null (no separator)
parseCollection( null )           ; // null
parseCollection( '' )             ; // null
see
parseIdentifier()

Returns the full {collection, key} pair.

parseKey()

Returns just the _key portion.

https://docs.arango.ai/arangodb/stable/aql/functions/document-object/#parse_collection
author

Marc Alcaraz

Return values
string|null —

The collection name, or null when $id is null / empty / has no /.

parseIdentifier()

Parses an ArangoDB document handle (`<collection>/<key>`) into its components.

parseIdentifier(string|null $id) : array{collection: string|null, key: string|null}|null

PHP mirror of the AQL function PARSE_IDENTIFIER. Useful when working with _id, _from or _to strings in PHP land — e.g. when iterating through edge documents returned by a model list() and only the _key or the collection name is needed.

Parameters
$id : string|null

The full document handle (e.g. "users/abc123").

Tags
example 
parseIdentifier( 'users/abc123' ) ;
// [ 'collection' => 'users' , 'key' => 'abc123' ]

parseIdentifier( 'just-a-key' ) ;
// [ 'collection' => null , 'key' => 'just-a-key' ]

parseIdentifier( null ) ; // null
parseIdentifier( '' )   ; // null
see
parseKey()

Returns just the _key portion.

parseCollection()

Returns just the collection name.

https://docs.arango.ai/arangodb/stable/aql/functions/document-object/#parse_identifier
author

Marc Alcaraz

Return values
array{collection: string|null, key: string|null}|null —

An associative array with collection and key keys, or null if $id is null / empty.

parseKey()

Returns the `_key` portion of an ArangoDB document handle (`<collection>/<key>`).

parseKey(string|null $id) : string|null

PHP mirror of the AQL function PARSE_KEY. If the input has no / separator it is returned as-is — the helper accepts both full handles ("users/abc123") and bare keys ("abc123") and always returns a usable _key string.

Parameters
$id : string|null

The full document handle (e.g. "users/abc123") or a bare _key.

Tags
example 
parseKey( 'users/abc123' ) ; // 'abc123'
parseKey( 'roles/42' )     ; // '42'
parseKey( 'just-a-key' )   ; // 'just-a-key' (passes through)
parseKey( null )           ; // null
parseKey( '' )             ; // null
see
parseIdentifier()

Returns the full {collection, key} pair.

parseCollection()

Returns just the collection name.

https://docs.arango.ai/arangodb/stable/aql/functions/document-object/#parse_key
author

Marc Alcaraz

Return values
string|null —

The _key portion, or null when $id is null / empty.

sortKeys()

Composes a comma-separated sort expression in the textual sort grammar (the same grammar consumed by `SortTrait::prepareSort` and the HTTP `?sort=` query parameter).

sortKeys(string ...$keys) : string

Each argument is a sort token, typically produced by ascKey() or descKey() but plain field constants are accepted as well (an unprefixed key implies ascending order).

Null and empty tokens are skipped via compile(), so callers can pass conditional tokens without array_filter() boilerplate.

Parameters
$keys : string

One or more sort tokens (e.g. 'name', '-created').

Tags
example 
use App\Enums\Prop;
use oihana\arango\enums\Arango;

use function oihana\arango\helpers\descKey;
use function oihana\arango\helpers\sortKeys;

sortKeys( descKey( Prop::CREATED ) )                                    ; // '-created'
sortKeys( descKey( Prop::CREATED ) , Prop::NAME )                       ; // '-created,name'
sortKeys( descKey( Prop::CREATED ) , descKey( Prop::NAME ) )            ; // '-created,-name'
sortKeys()                                                              ; // ''

Arango::SORT => sortKeys( descKey( Prop::CREATED ) , Prop::_KEY ) ;
see
ascKey()

Ascending sort token.

descKey()

Descending sort token.

author

Marc Alcaraz

Return values
string —

The comma-joined sort expression, or an empty string when no tokens are given.

On this page

Search results