Oihana Php Arango

ArangoClient

Read onlyYes

Entry point of the ArangoDB client.

Holds the connection configuration (ClientOptions) and the underlying HttpTransport, and exposes:

server-level operations (version(), listDatabases(), createDatabase(), dropDatabase()),
a factory for Database instances scoped to a specific database (database(?string $name = null)),
a low-level passthrough (request()) for server-global routes that must not carry the /_db/{name} prefix.

The transport is shared with every Database produced by this client, so all sub-objects benefit from the same connection pool, retry policy and host-ring failover.

Example:

$client = new ArangoClient
(
    new ClientOptions
    (
        database  : 'mydb' ,
        endpoints : [ 'tcp://127.0.0.1:8529' ] ,
        user      : 'root' ,
        password  : 'secret' ,
    )
) ;

$version = $client->version() ;
$db      = $client->database() ; // resolves to 'mydb' from the options

Constants

MODE_FIELD : string = 'mode': Field carrying the server mode (`default` / `readonly`) in the response of `GET /_admin/server/availability`.
RESULT_FIELD : string = 'result': Key carrying the payload in ArangoDB list responses.
TIME_FIELD : string = 'time': Field carrying the timestamp in the response of `GET /_admin/time`.

Properties

$options : ClientOptions
$transport : HttpTransport: Shared HTTP transport used by this client and every {@see Database} it produces.

Methods

__construct() : mixed
availability() : string|false: Probes the server's availability through `GET /_admin/server/availability`.
createDatabase() : void: Creates a new database on the server.
database() : Database: Returns a {@see Database} instance bound to the given name.
dropDatabase() : void: Drops a database from the server.
listDatabases() : array<int, string>: Returns the list of database names visible to the authenticated user.
login() : string: Authenticates against ArangoDB by posting `{username, password}` to the `/_open/auth` endpoint and stores the returned JWT in the transport for subsequent requests.
request() : HttpResponse: Low-level passthrough to the underlying transport for server-global routes.
time() : float: Returns the server's current system time as a Unix timestamp with sub-second precision (the PHP `microtime(true)` convention — a `float` in seconds rather than the ms tuple arangojs hands back from the same endpoint).
useBasicAuth() : void: Switches the client to Basic auth with the given credentials.
useBearerAuth() : void: Switches the client to JWT/Bearer mode with the given token.
version() : array<string, mixed>: Returns the ArangoDB server version and license information.

MODE_FIELD

Field carrying the server mode (`default` / `readonly`) in the response of `GET /_admin/server/availability`.


    private
        string
    MODE_FIELD
    = 'mode'

RESULT_FIELD

Key carrying the payload in ArangoDB list responses.


    private
        string
    RESULT_FIELD
    = 'result'

TIME_FIELD

Field carrying the timestamp in the response of `GET /_admin/time`.


    private
        string
    TIME_FIELD
    = 'time'

$options


        public
            ClientOptions
    $options

$transport

Shared HTTP transport used by this client and every {@see Database} it produces.


        public
            HttpTransport
    $transport

__construct()


    public
                    __construct(ClientOptions $options[, HttpTransport|null $transport = null ]) : mixed

Parameters

$options : ClientOptions: Connection options.
$transport : HttpTransport|null = null: Optional injectable transport (typically a transport wrapping a mocked Guzzle client in tests).

availability()

Probes the server's availability through `GET /_admin/server/availability`.


    public
                    availability([bool $graceful = true ]) : string|false

The endpoint returns the server's mode (one of ServerMode) on a 2xx response, and a 503 status code when the server is shutting down or in maintenance mode. This method surfaces the 503 branch as false by default (the $graceful knob), so a caller can use it as a single boolean health-check expression:

if ( $client->availability() === false )
{
    // server is unreachable / in maintenance — degrade gracefully
}

Pass $graceful: false to let a 503 surface as an HttpException alongside every other error — useful when a caller wants to distinguish "down" from "unreachable network" and react differently to each.

Non-503 transport errors (404, 500, network failures, …) always propagate, regardless of $graceful.

Parameters

$graceful : bool = true: When true (default), a 503 response yields false instead of throwing. When false, every error propagates as an ArangoException.

Return values

string|false —

One of the ServerMode constants when the server is up, false when graceful and the server is in maintenance.

createDatabase()

Creates a new database on the server.


    public
                    createDatabase(string $name) : void

Parameters

$name : string: Name of the database to create.

database()

Returns a {@see Database} instance bound to the given name.


    public
                    database([string|null $name = null ]) : Database

When $name is null the database configured in ClientOptions::$database is used. Throws when no database name is available from either source.

Parameters

$name : string|null = null

Return values

Database

dropDatabase()

Drops a database from the server.


    public
                    dropDatabase(string $name) : void

Parameters

$name : string: Name of the database to drop.

listDatabases()

Returns the list of database names visible to the authenticated user.


    public
                    listDatabases() : array<int, string>

Return values

array<int, string>

login()

Authenticates against ArangoDB by posting `{username, password}` to the `/_open/auth` endpoint and stores the returned JWT in the transport for subsequent requests.


    public
                    login(string $user, string $password) : string

Returns the raw JWT so the caller can forward it elsewhere (cache, another client, …) if needed. The basic credentials are also stored so the transport can transparently refresh the JWT on 401.

Parameters

$user : string
$password : string

Return values

string —

The JWT returned by the server.

request()

Low-level passthrough to the underlying transport for server-global routes.


    public
                    request(string $method, string $path[, array<string, mixed>|null $body = null ][, array<string, mixed> $query = [] ][, array<string, string> $headers = [] ]) : HttpResponse

The /_db/{database} URL prefix is never applied to these requests, even when ClientOptions::$database is set, so the caller can target global endpoints such as /_api/version or /_api/database.

Parameters

$method : string: HTTP verb.
$path : string: API path beginning with /.
$body : array<string, mixed>|null = null: Request body (JSON-encoded).
$query : array<string, mixed> = []: Query string parameters.
$headers : array<string, string> = []: Extra headers (merged with the per-request defaults).

Return values

HttpResponse

time()

Returns the server's current system time as a Unix timestamp with sub-second precision (the PHP `microtime(true)` convention — a `float` in seconds rather than the ms tuple arangojs hands back from the same endpoint).


    public
                    time() : float

Wraps GET /_admin/time. The endpoint is server-global (it does not depend on a specific database) — the client targets it through its databaseOverride: '' path.

Typical use cases:

calibrate an application clock against the server,
detect clock skew before issuing time-sensitive AQL (DATE_NOW() predicates, TTL index probes, …),
smoke-check connectivity with a tiny payload.

Return values

float —

Unix timestamp in seconds (with microsecond precision when the server provides it).

useBasicAuth()

Switches the client to Basic auth with the given credentials.


    public
                    useBasicAuth(string $user, string $password) : void

Subsequent requests carry Authorization: basic base64(user:password). Any bearer token previously set is cleared. Useful in tests or admin tooling that needs to switch identities at runtime.

Parameters

$user : string
$password : string

useBearerAuth()

Switches the client to JWT/Bearer mode with the given token.


    public
                    useBearerAuth(string|null $token) : void

Subsequent requests carry Authorization: bearer <token>. The basic credentials (if any) are kept around so the transport can refresh the JWT on 401 by re-logging in.

Pass null to revert to basic credentials (or to anonymous mode when none are configured).

Parameters

$token : string|null: JWT to send on subsequent requests.

version()

Returns the ArangoDB server version and license information.


    public
                    version() : array<string, mixed>

Return values

array<string, mixed>

ArangoClient

Tags

Table of Contents

Constants

Properties

Methods

Constants

MODE_FIELD

RESULT_FIELD

TIME_FIELD

Properties

$options

$transport

Methods

__construct()

Parameters

availability()

Parameters

Tags

Return values

createDatabase()

Parameters

Tags

database()

Parameters

Tags

Return values

dropDatabase()

Parameters

Tags

listDatabases()

Tags

Return values

login()

Parameters

Tags

Return values

request()

Parameters

Tags

Return values

time()

Tags

Return values

useBasicAuth()

Parameters

useBearerAuth()

Parameters

version()

Tags

Return values