Oihana Php Arango

EdgeCollection extends Collection

Read onlyYes

Edge-typed collection.

Inherits the full CRUD surface of Collection and adds three convenience methods to retrieve the edges touching a given vertex.

Implementation note: the ArangoDB /_api/simple/* endpoints (byExample, inEdges, outEdges, …) have been deprecated since ArangoDB 3.x and removed in 3.12+. This client therefore implements the equivalent operations as plain AQL queries. The default server-side edge index on _from / _to keeps them as fast as the removed simple endpoints used to be.

Example:

$follows = $db->edgeCollection( 'follows' ) ;

foreach ( $follows->outEdges( 'users/alice' ) as $edge )
{
    // every edge with _from == 'users/alice'
}

Properties

$database : Database
$name : string

Methods

__construct() : mixed
all() : Cursor: Returns a {@see Cursor} iterating over every document of the collection.
byExample() : Cursor: Returns a {@see Cursor} iterating over documents that match every key/value pair of `$example` (equality match — for richer predicates, drop down to {@see Database::query()} and write the AQL by hand).
count() : int: Returns the current number of documents in the collection.
create() : void: Overrides {@see Collection::create()} to default the new collection to {@see CollectionType::EDGE} when the caller does not set a type explicitly through `$options`.
createIndex() : array<string, mixed>: Creates a secondary index on this collection.
document() : Document: Fetches a single document by key.
documentExists() : bool: Returns true when a document with the given key exists in this collection.
drop() : void: Drops this collection from the server.
dropIndex() : void: Drops an index from this collection.
edges() : Cursor: Returns every edge connected to the given vertex on either side (i.e. `_from == $vertexId` OR `_to == $vertexId`).
exists() : bool: Returns true when this collection exists on the server.
firstExample() : Document|null: Returns the first document matching every key/value pair of `$example` (equality match), or `null` when no document matches.
getName() : string: Returns the collection name this instance is bound to.
import() : ImportResult: Bulk-imports an array of documents through the dedicated `POST /_api/import` endpoint.
index() : array<string, mixed>: Returns the server-side metadata of a single index.
indexes() : array<int, array<string, mixed>>: Returns the list of indexes defined on this collection.
inEdges() : Cursor: Returns every edge pointing AT the given vertex (target side, i.e. `_to == $vertexId`).
insert() : Document: Inserts a new document into the collection.
outEdges() : Cursor: Returns every edge originating FROM the given vertex (source side, i.e. `_from == $vertexId`).
properties() : array<string, mixed>: Returns the full server-side metadata of this collection (`GET /_api/collection/{name}/properties`).
remove() : Document: Removes a document by key.
removeAll() : array<int, Document>: Removes multiple documents from the collection in a single round-trip.
rename() : static: Renames the collection on the server and returns a NEW instance of the same class (`static`) bound to the new name. The current instance keeps pointing at the old name and should be discarded once `rename()` returns.
replace() : Document: Replaces an existing document with the given payload (PUT semantics).
replaceAll() : array<int, Document>: Replaces multiple documents in a single round-trip.
saveAll() : array<int, Document>: Inserts multiple documents in a single round-trip.
truncate() : void: Truncates the collection (removes every document, keeps the collection itself).
update() : Document: Partially updates an existing document with the given partial payload (PATCH semantics — only the supplied fields are touched).
updateAll() : array<int, Document>: Partially updates multiple documents in a single round-trip (PATCH semantics — only the supplied fields are touched on each document).

$database


        public
            Database
    $database

$name


        public
            string
    $name

__construct()


    public
                    __construct(Database $database, string $name) : mixed

Parameters

$database : Database: Parent database (provides the shared HTTP transport).
$name : string: Name of the target collection on the server.

all()

Returns a {@see Cursor} iterating over every document of the collection.


    public
                    all([int $limit = 0 ][, int $offset = 0 ]) : Cursor

Backed by a plain FOR doc IN @@col RETURN doc AQL query (the /_api/simple/all endpoint was deprecated in ArangoDB 3.x). Pagination is applied through optional LIMIT clauses — only non-zero values are emitted, so the default behaviour fetches the whole collection in lazy batches.

Equivalent to byExample([], $limit, $offset).

Parameters

$limit : int = 0: Maximum number of documents to return (0 = no LIMIT).
$offset : int = 0: Number of documents to skip before returning results (0 = no offset). Named after the AQL native LIMIT offset, count syntax.

Return values

Cursor

byExample()

Returns a {@see Cursor} iterating over documents that match every key/value pair of `$example` (equality match — for richer predicates, drop down to {@see Database::query()} and write the AQL by hand).


    public
                    byExample(array<string, mixed> $example[, int $limit = 0 ][, int $offset = 0 ]) : Cursor

Backed by a FOR doc IN @@col [FILTER doc.k1 == @v1 AND …] RETURN doc AQL query (the /_api/simple/by-example endpoint was deprecated in ArangoDB 3.x).

To avoid AQL injection through example keys, each key is validated against /^[a-zA-Z_][a-zA-Z0-9_.]*$/ — simple top-level attributes and dotted paths (address.city) are supported, anything else throws an InvalidArgumentException. Example values are always passed as bind variables and never inlined.

Parameters

$example : array<string, mixed>: Equality predicate (empty array = no FILTER).
$limit : int = 0: Maximum number of documents to return (0 = no LIMIT).
$offset : int = 0: Number of documents to skip before returning results (0 = no offset). Named after the AQL native LIMIT offset, count syntax.

Return values

Cursor

count()

Returns the current number of documents in the collection.


    public
                    count() : int

Return values

int

create()

Overrides {@see Collection::create()} to default the new collection to {@see CollectionType::EDGE} when the caller does not set a type explicitly through `$options`.


    public
                    create([array<string, mixed> $options = [] ]) : void

Parameters

$options : array<string, mixed> = []: Extra creation options.

createIndex()

Creates a secondary index on this collection.


    public
                    createIndex(IndexDefinition $definition) : array<string, mixed>

Parameters

$definition : IndexDefinition: Index definition built from one of the indexes value objects (PersistentIndex, GeoIndex, TtlIndex, FulltextIndex, …).

Return values

array<string, mixed> —

Raw server response (carries the assigned id, the resolved type, the indexed fields, …).

document()

Fetches a single document by key.


    public
                    document(string $key) : Document

Parameters

$key : string: The document key (_key).

Return values

Document

documentExists()

Returns true when a document with the given key exists in this collection.


    public
                    documentExists(string $key) : bool

Uses an HTTP HEAD request (no body) so the round-trip stays cheap. Any non-404 error is rethrown as an ArangoException.

Parameters

$key : string: The document key.

Return values

bool

drop()

Drops this collection from the server.


    public
                    drop() : void

dropIndex()

Drops an index from this collection.


    public
                    dropIndex(string $idOrName) : void

Accepts either a full server-side handle (users/12345 or users/idx_email_unique) or just the key / name part (12345, idx_email_unique) — the collection name is prefixed automatically when missing.

Parameters

$idOrName : string: Full handle or key/name of the index to drop.

edges()

Returns every edge connected to the given vertex on either side (i.e. `_from == $vertexId` OR `_to == $vertexId`).


    public
                    edges(string $vertexId) : Cursor

Parameters

$vertexId : string: Fully-qualified vertex identifier (e.g. users/alice).

Return values

Cursor

exists()

Returns true when this collection exists on the server.


    public
                    exists() : bool

Issues GET /_api/collection/{name} and treats a 404 as a clean "missing" — any other failure is rethrown as an ArangoException.

Return values

bool

firstExample()

Returns the first document matching every key/value pair of `$example` (equality match), or `null` when no document matches.


    public
                    firstExample(array<string, mixed> $example) : Document|null

Shortcut over byExample() that materialises the first row of the result cursor into a Document. The key validation rules from byExample() apply.

Parameters

$example : array<string, mixed>: Equality predicate.

Return values

Document|null

getName()

Returns the collection name this instance is bound to.


    public
                    getName() : string

Return values

string

import()

Bulk-imports an array of documents through the dedicated `POST /_api/import` endpoint.


    public
                    import(array<int, array<string, mixed>> $documents[, array<string, mixed> $options = [] ]) : ImportResult

Around 100× faster than saveAll() on large batches because the server skips the per-document parser / response builder and streams the input directly into the storage engine. The trade-off is that partial failures do not surface as per-row Document instances — the server returns aggregated counters (created / errors / empty / updated / ignored), exposed here as an ImportResult.

Each entry of $documents must be an associative array; objects are not accepted at this layer (call ->toArray() on the caller's side, or use saveAll() which returns typed Document instances).

Server-side options are forwarded as query parameters (booleans are stringified to the spelling Arango expects). Recognised keys include overwrite (truncate the target before importing), waitForSync, complete (abort on first error), details (populate ImportResult::$details), onDuplicate (one of the OnDuplicate constants), fromPrefix, toPrefix.

Example:

$result = $users->import
(
    [
        [ '_key' => 'alice' , 'name' => 'Alice' ] ,
        [ '_key' => 'bob'   , 'name' => 'Bob'   ] ,
    ] ,
    [
        'waitForSync' => true ,
        'onDuplicate' => OnDuplicate::UPDATE ,
        'details'     => true ,
    ] ,
) ;

if ( $result->hasErrors() )
{
    foreach ( $result->details as $message ) { error_log( $message ) ; }
}

Parameters

$documents : array<int, array<string, mixed>>: Documents to import.
$options : array<string, mixed> = []: Server-side options (overwrite, waitForSync, complete, details, onDuplicate, fromPrefix, toPrefix, …).

Return values

ImportResult

index()

Returns the server-side metadata of a single index.


    public
                    index(string $idOrName) : array<string, mixed>

Accepts either a full server-side handle (users/12345 or users/idx_email) or just the key / name part (12345, idx_email) — the collection name is prefixed automatically when missing.

Parameters

$idOrName : string: Full handle or key/name of the index.

Return values

array<string, mixed> —

Raw server response (id, type, fields, …).

indexes()

Returns the list of indexes defined on this collection.


    public
                    indexes() : array<int, array<string, mixed>>

Each entry is the raw server-side metadata (id, type, fields, …); IndexField constants can be used to read its keys safely.

Return values

array<int, array<string, mixed>>

inEdges()

Returns every edge pointing AT the given vertex (target side, i.e. `_to == $vertexId`).


    public
                    inEdges(string $vertexId) : Cursor

Parameters

$vertexId : string: Fully-qualified vertex identifier (e.g. users/alice).

Return values

Cursor

insert()

Inserts a new document into the collection.


    public
                    insert(array<string, mixed> $data[, array<string, mixed> $options = [] ]) : Document

The returned Document carries the server-assigned _key / _id / _rev; pass returnNew: true in $options to receive the full inserted payload merged into the result.

Parameters

$data : array<string, mixed>: Document payload.
$options : array<string, mixed> = []: Server-side options (returnNew, waitForSync, overwriteMode, …).

Return values

Document

outEdges()

Returns every edge originating FROM the given vertex (source side, i.e. `_from == $vertexId`).


    public
                    outEdges(string $vertexId) : Cursor

Parameters

$vertexId : string: Fully-qualified vertex identifier (e.g. users/alice).

Return values

Cursor

properties()

Returns the full server-side metadata of this collection (`GET /_api/collection/{name}/properties`).


    public
                    properties() : array<string, mixed>

The response is returned as a raw associative array — fields include the canonical CollectionField entries (name, isSystem, type, …) plus the type-specific details (keyOptions, numberOfShards, replicationFactor, writeConcern, cacheEnabled, globallyUniqueId, id, status, …).

Return values

array<string, mixed>

remove()

Removes a document by key.


    public
                    remove(string $key[, array<string, mixed> $options = [] ]) : Document

The returned Document carries the meta returned by the server (_key / _id / _rev); pass returnOld: true in $options to receive the deleted payload merged into the result.

Parameters

$key : string: Document key.
$options : array<string, mixed> = []: Server-side options (returnOld, waitForSync, …).

Return values

Document

removeAll()

Removes multiple documents from the collection in a single round-trip.


    public
                    removeAll(array<int, string|array<string, mixed>> $selectors[, array<string, mixed> $options = [] ]) : array<int, Document>

$selectors accepts either raw keys (strings) or objects carrying _key / _id — both forms are forwarded as-is to ArangoDB in the request body of DELETE /_api/document/{collection}.

The server processes the array entry-by-entry: each entry produces an entry in the response array, either the deleted meta (_key / _id / _rev plus optional old payload when returnOld: true) or an error object (error: true, errorNum, errorMessage). Partial failures do not abort the batch — the caller inspects each returned Document to decide what to do.

Parameters

$selectors : array<int, string|array<string, mixed>>: Document keys or {_key, …} / {_id, …} objects.
$options : array<string, mixed> = []: Server-side options (returnOld, waitForSync, silent, ignoreRevs, refillIndexCaches, …).

Return values

array<int, Document> —

One entry per input selector, same order as the input.

rename()

Renames the collection on the server and returns a NEW instance of the same class (`static`) bound to the new name. The current instance keeps pointing at the old name and should be discarded once `rename()` returns.


    public
                    rename(string $newName) : static

Cluster note: ArangoDB rejects rename operations on cluster deployments (only single-server setups support it). The error is surfaced as an ArangoException.

Parameters

$newName : string: New collection name.

Return values

static —

New instance bound to $newName.

replace()

Replaces an existing document with the given payload (PUT semantics).


    public
                    replace(string $key, array<string, mixed> $data[, array<string, mixed> $options = [] ]) : Document

Parameters

$key : string: Document key.
$data : array<string, mixed>: Replacement payload.
$options : array<string, mixed> = []: Server-side options (returnNew, returnOld, ignoreRevs, waitForSync, …).

Return values

Document

replaceAll()

Replaces multiple documents in a single round-trip.


    public
                    replaceAll(array<int, array<string, mixed>> $documents[, array<string, mixed> $options = [] ]) : array<int, Document>

Each entry of $documents must carry the _key (or _id) of the target document; the rest of the payload becomes the new content of that document (PUT semantics — fields absent from the payload are dropped).

The server processes the array entry-by-entry: each entry produces an entry in the response array, either the meta (_key / _id / _rev + optional new / old) or an error object (error: true, errorNum, errorMessage). Partial failures do not abort the batch.

Parameters

$documents : array<int, array<string, mixed>>: Replacement payloads (each MUST include _key or _id).
$options : array<string, mixed> = []: Server-side options (returnNew, returnOld, ignoreRevs, silent, waitForSync, …).

Return values

array<int, Document> —

One entry per input document, same order as the input.

saveAll()

Inserts multiple documents in a single round-trip.


    public
                    saveAll(array<int, array<string, mixed>> $documents[, array<string, mixed> $options = [] ]) : array<int, Document>

Each entry of $documents is treated as a brand-new document (POST semantics). The server processes the array entry-by-entry: each entry produces an entry in the response array, either the inserted meta (_key / _id / _rev + optional new) or an error object (error: true, errorNum, errorMessage). Partial failures do not abort the batch.

Parameters

$documents : array<int, array<string, mixed>>: Documents to insert.
$options : array<string, mixed> = []: Server-side options (returnNew, overwriteMode, keepNull, mergeObjects, silent, waitForSync, …).

Return values

array<int, Document> —

One entry per input document, same order as the input.

truncate()

Truncates the collection (removes every document, keeps the collection itself).


    public
                    truncate() : void

update()

Partially updates an existing document with the given partial payload (PATCH semantics — only the supplied fields are touched).


    public
                    update(string $key, array<string, mixed> $partial[, array<string, mixed> $options = [] ]) : Document

Parameters

$key : string: Document key.
$partial : array<string, mixed>: Partial payload.
$options : array<string, mixed> = []: Server-side options (returnNew, returnOld, keepNull, mergeObjects, …).

Return values

Document

updateAll()

Partially updates multiple documents in a single round-trip (PATCH semantics — only the supplied fields are touched on each document).


    public
                    updateAll(array<int, array<string, mixed>> $patches[, array<string, mixed> $options = [] ]) : array<int, Document>

Each entry of $patches must carry the _key (or _id) of the target document; the rest of the payload is merged into that document on the server.

Parameters

$patches : array<int, array<string, mixed>>: Patch payloads (each MUST include _key or _id).
$options : array<string, mixed> = []: Server-side options (returnNew, returnOld, keepNull, mergeObjects, ignoreRevs, silent, waitForSync, …).

Return values

array<int, Document> —

One entry per input patch, same order as the input.

EdgeCollection extends Collection

Tags

Table of Contents

Properties

Methods

Properties

$database

$name

Methods

__construct()

Parameters

all()

Parameters

Tags

Return values

byExample()

Parameters

Tags

Return values

count()

Tags

Return values

create()

Parameters

Tags

createIndex()

Parameters

Tags

Return values

document()

Parameters

Tags

Return values

documentExists()

Parameters

Tags

Return values

drop()

Tags

dropIndex()

Parameters

Tags

edges()

Parameters

Tags

Return values

exists()

Tags

Return values

firstExample()

Parameters

Tags

Return values

getName()

Return values

import()

Parameters

Tags

Return values

index()

Parameters

Tags

Return values

indexes()

Tags

Return values

inEdges()

Parameters

Tags

Return values

insert()

Parameters

Tags

Return values

outEdges()

Parameters

Tags

Return values

properties()

Tags