Oihana Php Arango

IndexManagementTrait uses trait:short

Index-management surface of the {@see \oihana\arango\db\ArangoDB} façade — everything that touches collection indexes and nothing else: creation, removal, lookup, and the declarations ↔ server conformity primitives of the `doctor` family (`indexesDiff()` / `indexesSync()`).

Composes CollectionManagementTrait (the shared $database scope and resolveCollectionName()). createIndex() / dropIndex() log a warning and return null / false on failure; getIndex() / getIndexes() let the oihana\arango\clients\exceptions\ArangoException propagate directly.

Properties

$database : Database

Methods

collectionCreate() : bool: Creates a new collection if it does not already exist.
collectionDiff() : DiffReport: Compares a declared collection with the server state and reports the difference — the collection half of the `doctor` diagnosis.
collectionDrop() : bool: Drops a collection if it exists.
collectionExists() : bool: Checks if a collection exists.
collectionRename() : bool: Renames a collection if it exists.
collectionTruncate() : bool: Truncates a collection if it exists.
createIndex() : array<string|int, mixed>|null: Creates an index on a collection.
dropIndex() : bool: Drops an index from a collection.
getIndex() : array<string|int, mixed>: Returns a specific index of a collection by its ID.
getIndexes() : array<string|int, mixed>: Returns all indexes of a collection.
indexesDiff() : DiffReport: Compares the declared indexes of a collection with the server state and reports the differences in one aggregated report — the index half of the `doctor` diagnosis.
indexesSync() : DiffReport: Reconciles the declared indexes of a collection with the server: missing indexes are created; drifted ones are repaired by **drop + recreate** — but only when `$force` is true, because an index is immutable and the rebuild opens a window where queries lose it (and a unique index may fail to recreate over duplicated data). Without `$force` the drift is only reported. Server indexes that no declaration mentions are never touched.
resolveCollectionName() : string: Resolves a collection reference (string name or {@see Collection} client handle) to its string name.
canonicaliseInvertedBodies() : array{0: array, 1: array}: Canonicalises a declared inverted-index body and its matched server body so the per-key comparison of {@see compareIndexBody()} no longer trips over the shapes the server normalises:
compareIndexBody() : array<int, string>: Accumulates one line per declared key whose server value differs — see {@see indexesDiff()} for the comparison semantics. The `fields` lists compare order-sensitively; every drift line carries the `drop + recreate` reminder (indexes are immutable).
fieldsSignature() : array<int, mixed>: Returns the ordered `fields` signature used to match an unnamed index.
indexBody() : array<string, mixed>: Normalises a declared index ({@see IndexDefinition} value object, {@see IndexOptions} value object or raw array) into its comparable body: the serialised creation payload, minus `inBackground` (a creation-time option the server never echoes).
indexLabel() : string: Returns the human label of a declared index for the change lines: its `name` when declared, its `type(field, …)` signature otherwise.
matchServerIndex() : array<string, mixed>|null: Finds the server index a declared body targets: by `name` when one is declared, by `type` + ordered `fields` signature otherwise. Returns null when nothing matches (the index is missing).
normalisePrimarySort() : mixed: Folds a `primarySort` definition to one canonical spelling of its sort direction: the declared `{ field, direction:"asc"|"desc" }` and the server's `{ field, asc:bool }` both become `{ field, asc:bool }`, so the two compare equal. Non-array input and direction-less fields pass through untouched.
projectOntoDeclared() : mixed: Projects `$actual` onto the shape of `$declared`, recursively: only the keys present in `$declared` are kept (by key for maps, by position for lists), so the defaults the server fills in but the declaration omits never read as drift. A scalar (or a `$declared` leaf) returns `$actual` verbatim.
serverIndexes() : array<int, array<string, mixed>>: Returns the server indexes of a collection minus the automatic `primary` and `edge` ones — the comparison scope of {@see indexesDiff()} / {@see indexesSync()}.

$database


        protected
            Database
    $database

Database scope shared with the parent façade.

collectionCreate()

Creates a new collection if it does not already exist.


    public
                    collectionCreate(string $name[, array<string, mixed> $options = [] ]) : bool

Parameters

$name : string: The name of the new collection.
$options : array<string, mixed> = []: Forwarded to POST /_api/collection (type, waitForSync, keyOptions, numberOfShards, replicationFactor, writeConcern, shardKeys, shardingStrategy, schema, …).

Return values

bool —

TRUE when the collection has been created, FALSE when it already existed or the request failed.

collectionDiff()

Compares a declared collection with the server state and reports the difference — the collection half of the `doctor` diagnosis.


    public
                    collectionDiff(string $name[, int|null $type = null ]) : DiffReport

The check is existence first (DiffStatus::MISSING when the collection is absent), then — when $type is given — the collection type (2 document / 3 edge): a mismatch is reported as DiffStatus::DRIFTED (a collection type cannot be changed, the repair is manual by design).

Parameters

$name : string: The name of the collection.
$type : int|null = null: The declared collection type (2 document, 3 edge), or null to skip the type check.

Return values

DiffReport —

The typed report (DiffKind::COLLECTION).

collectionDrop()

Drops a collection if it exists.


    public
                    collectionDrop(string $name) : bool

Parameters

$name : string: The name of the collection.

Return values

bool —

TRUE when the collection has been dropped, FALSE otherwise.

collectionExists()

Checks if a collection exists.


    public
                    collectionExists(string $name) : bool

Parameters

$name : string: The name of the collection.

Return values

bool

collectionRename()

Renames a collection if it exists.


    public
                    collectionRename(string $oldName, string $name) : bool

Parameters

$oldName : string: The current name of the collection.
$name : string: The new name of the collection.

Return values

bool —

TRUE when the collection has been renamed.

collectionTruncate()

Truncates a collection if it exists.


    public
                    collectionTruncate(string $name) : bool

Parameters

$name : string: The name of the collection.

Return values

bool —

TRUE when the collection has been truncated.

createIndex()

Creates an index on a collection.


    public
                    createIndex(string|Collection $collection, IndexDefinition|IndexOptions|array<string|int, mixed> $indexOptions) : array<string|int, mixed>|null

Parameters

$collection : string|Collection: Collection name or Collection client handle.
$indexOptions : IndexDefinition|IndexOptions|array<string|int, mixed>: An IndexDefinition value object (e.g. InvertedIndex), an IndexOptions value object, or a raw associative array matching the POST /_api/index body.

Return values

array<string|int, mixed>|null —

The server response of the created index, or null on failure.

dropIndex()

Drops an index from a collection.


    public
                    dropIndex(string|Collection $collection[, string|null $indexHandle = null ]) : bool

Parameters

$collection : string|Collection: Collection name or Collection handle — or the full index handle (collection/indexId) when $indexHandle is null.
$indexHandle : string|null = null: Index id / name suffix; when null, $collection is treated as the full handle.

Return values

bool —

TRUE when the index has been dropped.

getIndex()

Returns a specific index of a collection by its ID.


    public
                    getIndex(string $collection, string $indexId) : array<string|int, mixed>

Parameters

$collection : string: The name of the collection.
$indexId : string: The index ID (full handle or bare key — bare keys are auto-prefixed with the collection name).

Return values

array<string|int, mixed> —

The index definition from the server.

getIndexes()

Returns all indexes of a collection.


    public
                    getIndexes(string $name) : array<string|int, mixed>

Parameters

$name : string: The name of the collection.

Return values

array<string|int, mixed> —

The indexes array from the server response.

indexesDiff()

Compares the declared indexes of a collection with the server state and reports the differences in one aggregated report — the index half of the `doctor` diagnosis.


    public
                    indexesDiff(string $collection, array<int, IndexDefinition|IndexOptions|array<string, mixed>> $indexes) : DiffReport

Matching: a declared index is looked up on the server by its name when one is declared, by its type + fields signature otherwise. The comparison covers every declared key (fields order-sensitively — ["a","b"] and ["b","a"] are different indexes) and ignores the server-side extras the declaration does not mention (id, selectivityEstimate, …); inBackground is a creation-time option never echoed by the server, it is excluded. The automatic primary and edge indexes are out of scope both ways. Server indexes that no declaration mentions are reported as drift.

Statuses: declared indexes absent from the server only → DiffStatus::MISSING (safe to create); any definition mismatch or undeclared server index → DiffStatus::DRIFTED (an index is immutable — repairing means drop + recreate, see indexesSync() $force); a missing collection → DiffStatus::INVALID.

Inverted indexes are diffed canonically: a declared string field ("name") is lined up with the server's { name } object, the primarySort direction is normalised across its direction / asc spellings, and the server defaults the declaration omits (compression, per-field flags, …) are projected away — so an inverted index that is actually in sync no longer reads as drift.

Parameters

$collection : string: The name of the collection.
$indexes : array<int, IndexDefinition|IndexOptions|array<string, mixed>>: The declared indexes (the model AQL::INDEXES list).

Return values

DiffReport —

The typed report (DiffKind::INDEXES).

indexesSync()

Reconciles the declared indexes of a collection with the server: missing indexes are created; drifted ones are repaired by **drop + recreate** — but only when `$force` is true, because an index is immutable and the rebuild opens a window where queries lose it (and a unique index may fail to recreate over duplicated data). Without `$force` the drift is only reported. Server indexes that no declaration mentions are never touched.


    public
                    indexesSync(string $collection, array<int, IndexDefinition|IndexOptions|array<string, mixed>> $indexes[, bool $force = false ]) : DiffReport

Parameters

$collection : string: The name of the collection.
$indexes : array<int, IndexDefinition|IndexOptions|array<string, mixed>>: The declared indexes (the model AQL::INDEXES list).
$force : bool = false: Allow the drop + recreate of drifted indexes.

Return values

DiffReport —

The indexesDiff() report, with $applied set when at least one index has been created or rebuilt.

resolveCollectionName()

Resolves a collection reference (string name or {@see Collection} client handle) to its string name.


    protected
                    resolveCollectionName(string|Collection $collection) : string

Parameters

$collection : string|Collection

Return values

string

canonicaliseInvertedBodies()

Canonicalises a declared inverted-index body and its matched server body so the per-key comparison of {@see compareIndexBody()} no longer trips over the shapes the server normalises:


    private
                    canonicaliseInvertedBodies(array<string, mixed> $declared, array<string, mixed> $actual) : array{0: array, 1: array}

fields — a declared string "x" is the server's { name:"x", … }, so declared strings are lifted to { name } objects;
primarySort — the declared { direction:"asc" } and the server's { asc:true } are folded to one spelling (see normalisePrimarySort());
features — compared order-insensitively (the server may reorder them);
fields / primarySort / storedValues — every server key the declaration does not mention (compression, per-field flags, …) is projected away (see projectOntoDeclared()), per the "compare only what is declared" contract.

Parameters

$declared : array<string, mixed>: The declared inverted-index body.
$actual : array<string, mixed>: The matched server index body.

Return values

array{0: array, 1: array} —

The canonicalised [ declared , actual ] pair.

compareIndexBody()

Accumulates one line per declared key whose server value differs — see {@see indexesDiff()} for the comparison semantics. The `fields` lists compare order-sensitively; every drift line carries the `drop + recreate` reminder (indexes are immutable).


    private
                    compareIndexBody(string $label, array<string, mixed> $body, array<string, mixed> $actual) : array<int, string>

Parameters

$label : string: The declared index label used in the change lines.
$body : array<string, mixed>: The declared index body (indexBody()).
$actual : array<string, mixed>: The matched server index.

Return values

array<int, string>

fieldsSignature()

Returns the ordered `fields` signature used to match an unnamed index.


    private
                    fieldsSignature(array<string, mixed> $body) : array<int, mixed>

For an inverted index the server expands each declared string field into a { name, … } object, so both sides are reduced to their bare attribute names; every other type keeps its raw fields list.

Parameters

$body : array<string, mixed>: The declared or server index body.

Return values

array<int, mixed>

indexBody()

Normalises a declared index ({@see IndexDefinition} value object, {@see IndexOptions} value object or raw array) into its comparable body: the serialised creation payload, minus `inBackground` (a creation-time option the server never echoes).


    private
                    indexBody(IndexDefinition|IndexOptions|array<string, mixed> $declared) : array<string, mixed>

Parameters

$declared : IndexDefinition|IndexOptions|array<string, mixed>

Return values

array<string, mixed>

indexLabel()

Returns the human label of a declared index for the change lines: its `name` when declared, its `type(field, …)` signature otherwise.


    private
                    indexLabel(array<string, mixed> $body) : string

Parameters

$body : array<string, mixed>: The declared index body.

Return values

string

matchServerIndex()

Finds the server index a declared body targets: by `name` when one is declared, by `type` + ordered `fields` signature otherwise. Returns null when nothing matches (the index is missing).


    private
                    matchServerIndex(array<string, mixed> $body, array<int, array<string, mixed>> $actual) : array<string, mixed>|null

Parameters

$body : array<string, mixed>: The declared index body.
$actual : array<int, array<string, mixed>>: The non-system server indexes.

Return values

array<string, mixed>|null

normalisePrimarySort()

Folds a `primarySort` definition to one canonical spelling of its sort direction: the declared `{ field, direction:"asc"|"desc" }` and the server's `{ field, asc:bool }` both become `{ field, asc:bool }`, so the two compare equal. Non-array input and direction-less fields pass through untouched.


    private
                    normalisePrimarySort(mixed $primarySort) : mixed

Parameters

$primarySort : mixed: The declared or server primarySort value.

Return values

mixed —

The canonicalised value (an array when the input was one).

projectOntoDeclared()

Projects `$actual` onto the shape of `$declared`, recursively: only the keys present in `$declared` are kept (by key for maps, by position for lists), so the defaults the server fills in but the declaration omits never read as drift. A scalar (or a `$declared` leaf) returns `$actual` verbatim.


    private
                    projectOntoDeclared(mixed $declared, mixed $actual) : mixed

Parameters

$declared : mixed: The declared sub-tree.
$actual : mixed: The matched server sub-tree.

Return values

mixed —

The server value reduced to the declared shape.

serverIndexes()

Returns the server indexes of a collection minus the automatic `primary` and `edge` ones — the comparison scope of {@see indexesDiff()} / {@see indexesSync()}.


    private
                    serverIndexes(string $collection) : array<int, array<string, mixed>>

Parameters

$collection : string: The name of the collection.

Return values

array<int, array<string, mixed>>

IndexManagementTrait uses trait:short

Tags

Table of Contents

Properties

Methods

Properties

$database

Methods

collectionCreate()

Parameters

Return values

collectionDiff()

Parameters

Return values

collectionDrop()

Parameters

Return values

collectionExists()

Parameters

Return values

collectionRename()

Parameters

Tags

Return values

collectionTruncate()

Parameters

Return values

createIndex()

Parameters

Tags

Return values

dropIndex()

Parameters

Return values

getIndex()

Parameters

Tags

Return values

getIndexes()

Parameters

Tags

Return values

indexesDiff()

Parameters

Tags

Return values

indexesSync()

Parameters

Tags

Return values

resolveCollectionName()

Parameters

Return values

canonicaliseInvertedBodies()

Parameters

Return values

compareIndexBody()

Parameters

Return values

fieldsSignature()

Parameters

Return values

indexBody()

Parameters

Tags

Return values

indexLabel()

Parameters

Return values

matchServerIndex()

Parameters

Return values

normalisePrimarySort()

Parameters

Return values

projectOntoDeclared()

Parameters

Return values

serverIndexes()

Parameters