Oihana PHP Arango

DoctorTrait

The model-level structure health check — the `doctor` of a model.

A model declares its desired structure through its DI definition: a collection (AQL::COLLECTION + type), indexes (AQL::INDEXES) and optionally an ArangoSearch View (AQL::VIEW). The lazy provisioning only ever creates what is missing at first boot — it never updates anything afterwards, so editing a declaration leaves every existing environment silently out of date (an added index is never created, an added View field is never indexed).

This trait closes that gap with two explicit operations:

  • diagnose() answers "does the server still match what this model declares?" — read-only, one DiffReport per structure object;
  • repair() reconciles the server with the declarations — creates what is missing, resynchronizes the View, and (only when forced) rebuilds drifted indexes.

Both are meant to be run at deployment time (the doctor action of command:arangodb calls them on every configured model), not on the request path.

Tags
author

Marc Alcaraz (ekameleon)

since
1.2.0

Table of Contents

Methods

diagnose()  : array<string|int, DiffReport>
Compares everything this model declares with the server state, without touching anything — the read-only half of {@see repair()}.
repair()  : array<string|int, DiffReport>
Reconciles the server with everything this model declares — the acting half of {@see diagnose()}:

Methods

diagnose()

Compares everything this model declares with the server state, without touching anything — the read-only half of {@see repair()}.

public diagnose() : array<string|int, DiffReport>

The returned list carries one DiffReport per declared structure object, in dependency order:

  1. the collection (DiffKind::COLLECTION) — existence and type (2 document / 3 edge);
  2. the declared indexes (DiffKind::INDEXES, only when the model declares AQL::INDEXES) — one aggregated report: missing indexes, definition drifts (immutable → drop + recreate required), server indexes that are no longer declared;
  3. the View (DiffKind::VIEW, only when the model declares an AQL::VIEW block) — the SearchTrait::viewDiff() report with its declaration-coherence checks.

A model without a collection resolves to a single DiffStatus::INVALID report; without a database to a single DiffStatus::UNREACHABLE report.

Tags
throws
ReflectionException

When a declared IndexOptions cannot be serialised.

Return values
array<string|int, DiffReport> —

One report per declared structure object.

repair()

Reconciles the server with everything this model declares — the acting half of {@see diagnose()}:

public repair([bool $force = false ]) : array<string|int, DiffReport>
  1. a missing collection is created with its declared type and its declared indexes (exactly what the lazy provisioning would do);
  2. missing indexes are created on an existing collection — the case the lazy provisioning never covers; a drifted index is only rebuilt (drop + recreate) when $force is true, because the rebuild opens a window where queries lose the index and a unique index may fail to recreate over duplicated data;
  3. the View is created or resynchronized through SearchTrait::viewSync() (updateProperties(), the View stays queryable while re-indexing).

DiffStatus::INVALID and DiffStatus::UNREACHABLE reports are never acted on; a drifted collection type is never repaired (recreating a collection means losing its documents — that is a migration, not a repair).

Parameters
$force : bool = false

Allow the drop + recreate of drifted indexes.

Tags
throws
ReflectionException

When a declared IndexOptions cannot be serialised.

Return values
array<string|int, DiffReport> —

The diagnose() reports, with $applied set on every object actually created or updated.

On this page

Search results