Oihana PHP Arango

AnalyzerManagementTrait uses trait:short

Analyzer management methods shared by the {@see \oihana\arango\db\ArangoDB} façade — the analyzer counterpart of {@see ViewManagementTrait}.

Like the collection and view methods, every operation is defensive: a missing server resolves to a safe value (false, an empty list, or an DiffStatus::UNREACHABLE report) instead of throwing, so coherence checks stay safe without a database.

Unlike Views, an analyzer is immutable server-side: a drifted analyzer cannot be patched, only dropped and recreated — which cascades to every View that references it. analyzerDiff() therefore reports a drift (with the dependent Views) but analyzerSync() only creates the missing ones; repairing a drifted analyzer is a deliberate operation (a migration, or the --force cascade — see the arango:analyzers action).

Tags
author

Marc Alcaraz (ekameleon)

since
1.2.0

Table of Contents

Properties

$database  : Database

Methods

analyzerDependentViews()  : array<int, string>
Returns the names of the Views whose links reference the given analyzer (at link level or on any nested field), so a caller can know what a drop + recreate of the analyzer would cascade to.
analyzerDiff()  : DiffReport
Compares a declared analyzer with the server state and reports the differences — the read-only half of {@see analyzerSync()}.
analyzerExists()  : bool
Checks if an analyzer exists — built-in analyzers (`identity`, `text_en`, `text_fr`, …) are always reported by the server.
analyzerSync()  : DiffReport
Reconciles a declared analyzer with its server state.
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.
resolveCollectionName()  : string
Resolves a collection reference (string name or {@see Collection} client handle) to its string name.
comparePipeline()  : array<int, string>
Compares a declared `pipeline` sub-analyzer chain with the server one using declaration-oriented (subset) semantics — the same rule the top-level property loop gets for free by iterating only the declared keys.
linksReferenceAnalyzer()  : bool
Walks a link node (and recursively its `fields`) and tells whether any `analyzers` list references the given analyzer (short form).
normalizeAnalyzerValue()  : mixed
Normalizes a property value for an order-insensitive comparison: lists are sorted, maps are key-sorted, recursively; scalars pass through.
rebuildDependentViews()  : void
Rebuilds the inverted index of every View referencing the analyzer, by removing then re-adding each referencing collection link. That remove + re-add is the only thing the server treats as a real rebuild after the analyzer was recreated — re-applying an identical link is a no-op, and a recreated analyzer otherwise leaves a stale index. Used by the forced cascade of {@see analyzerSync()}.
stripAnalyzerNamespace()  : string
Strips the `dbname::` namespace prefix the server prepends to analyzer names, leaving the short name links and declarations use.

Properties

Methods

analyzerDependentViews()

Returns the names of the Views whose links reference the given analyzer (at link level or on any nested field), so a caller can know what a drop + recreate of the analyzer would cascade to.

public analyzerDependentViews(string $name) : array<int, string>

Names are compared by their short form (the dbname:: prefix the server may carry is stripped on both sides). Defensive: returns an empty list when the server is unreachable.

Parameters
$name : string

The analyzer name.

Return values
array<int, string> —

The dependent View names.

analyzerDiff()

Compares a declared analyzer with the server state and reports the differences — the read-only half of {@see analyzerSync()}.

public analyzerDiff(AnalyzerDefinition $definition) : DiffReport

The comparison is declaration-oriented: the type must match exactly, declared properties must be present and equal (server defaults the declaration omits are ignored), and features are compared as a set (order-insensitive). A difference yields DiffStatus::DRIFTED with a drop + recreate required note and the dependent Views (immutable analyzer). An empty name is DiffStatus::INVALID.

Parameters
$definition : AnalyzerDefinition

The declared analyzer.

Return values
DiffReport —

The typed report — see DiffStatus for the possible statuses.

analyzerExists()

Checks if an analyzer exists — built-in analyzers (`identity`, `text_en`, `text_fr`, …) are always reported by the server.

public analyzerExists(string $name) : bool
Parameters
$name : string

The name of the analyzer.

Return values
bool

analyzerSync()

Reconciles a declared analyzer with its server state.

public analyzerSync(AnalyzerDefinition $definition[, bool $force = false ]) : DiffReport

A missing analyzer is always created. A drifted analyzer is only repaired when $force is true — it is immutable, so repairing it means a drop + recreate that cascades to its dependent Views (their inverted index is rebuilt). Without $force a drift is left untouched (the safe default — repair it deliberately, through a migration). DiffStatus::IN_SYNC, DiffStatus::INVALID and DiffStatus::UNREACHABLE reports are always returned as-is.

⚠ The forced repair is not transactional: between the drop and the recreate the analyzer briefly does not exist, and a failure there leaves the dependent Views referencing a missing analyzer. The truly safe path for changing an analyzer is a new-name migration (see db/analyzers.md).

Parameters
$definition : AnalyzerDefinition

The declared analyzer.

$force : bool = false

Allow the drop + recreate (and dependent-View rebuild) of a drifted analyzer.

Return values
DiffReport —

The analyzerDiff() report, with $applied set when the analyzer has been created or recreated.

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.

Tags
throws
ArangoException

When the rename request fails on a collection that does exist (e.g. cluster restriction, duplicate target name).

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.

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

comparePipeline()

Compares a declared `pipeline` sub-analyzer chain with the server one using declaration-oriented (subset) semantics — the same rule the top-level property loop gets for free by iterating only the declared keys.

private comparePipeline(string $name, mixed $declared, mixed $server) : array<int, string>

A pipeline analyzer nests its sub-analyzers inside a list, and the server reads each one back with every default property filled in (a declared norm carrying only { locale } returns { locale, case, accent }; an ngram returns its startMarker / endMarker / streamType defaults too). A plain deep-equality of the two lists would therefore flag a permanent false drift — the very bug the identity analyzer hit on View links. Instead each member is matched by position (the chain order is significant) and by type, and only the declared sub-properties are checked: server defaults the declaration omits are ignored. A RawAnalyzer dumped from the server (all defaults present) stays a valid round-trip.

Parameters
$name : string

The analyzer name, for the change lines.

$declared : mixed

The declared properties.pipeline value.

$server : mixed

The server properties.pipeline value.

Return values
array<int, string> —

The change lines, empty when the chains are equivalent.

linksReferenceAnalyzer()

Walks a link node (and recursively its `fields`) and tells whether any `analyzers` list references the given analyzer (short form).

private linksReferenceAnalyzer(array<string, mixed> $node, string $needle) : bool
Parameters
$node : array<string, mixed>

A link node or the whole links map.

$needle : string

The analyzer short name to look for.

Return values
bool

normalizeAnalyzerValue()

Normalizes a property value for an order-insensitive comparison: lists are sorted, maps are key-sorted, recursively; scalars pass through.

private normalizeAnalyzerValue(mixed $value) : mixed
Parameters
$value : mixed

rebuildDependentViews()

Rebuilds the inverted index of every View referencing the analyzer, by removing then re-adding each referencing collection link. That remove + re-add is the only thing the server treats as a real rebuild after the analyzer was recreated — re-applying an identical link is a no-op, and a recreated analyzer otherwise leaves a stale index. Used by the forced cascade of {@see analyzerSync()}.

private rebuildDependentViews(string $name) : void
Parameters
$name : string

The analyzer that was just recreated.

Tags
throws
ArangoException

When a View update fails.

stripAnalyzerNamespace()

Strips the `dbname::` namespace prefix the server prepends to analyzer names, leaving the short name links and declarations use.

private stripAnalyzerNamespace(string $name) : string
Parameters
$name : string
Return values
string
On this page

Search results