Oihana PHP Arango

DocumentsReplaceTrait uses trait:short, \oihana\models\traits\signals\HasReplaceSignals

Provides helpers to build and execute **REPLACE** AQL operations on ArangoDB documents.

This trait is responsible for fully replacing existing documents in a collection using a dynamically generated AQL query with bind variables.

Unlike the aqlUpdate function, which performs a partial update and only modifies the specified attributes, REPLACE removes all existing attributes of the document, except for immutable system attributes (_key, _id, _rev), and replaces them with the attributes from the provided document.

AQL Syntax

// Basic replace using a document key:
REPLACE @key WITH { ...newAttributes } IN @@collection [OPTIONS {...}]

// Replace using a FOR ... FILTER clause:
FOR doc IN @@collection
    FILTER doc._key == @key
    REPLACE { ...newAttributes } IN @@collection [OPTIONS {...}]
    RETURN NEW

Examples

  1. Simple replace by key:
$result = $this->replace
([
    Arango::DOC   => [ 'name' => 'Marc', 'city' => 'Marseille' ],
    Arango::VALUE => '2531394',
    Arango::BINDS => [ '@collection' => 'places' ]
]);
// => REPLACE @key WITH { name:'Marc', city:'Marseille' } IN @@collection RETURN NEW
  1. Replace with excluded attributes:
$result = $this->replace
([
    Arango::DOC      => [ 'name' => 'Marc', 'city' => 'Marseille', 'created' => '...' ],
    Arango::EXCLUDES => [ 'created' ],
    Arango::VALUE    => '2531394',
    Arango::BINDS    => [ '@collection' => 'places' ]
]);
// => The "created" field will NOT be replaced
  1. Replace and return the OLD document:
$result = $this->replace
([
    Arango::DOC    => [ 'name' => 'Marc' ],
    Arango::VALUE  => '2531394',
    Arango::BINDS  => [ '@collection' => 'places' ],
    Arango::RETURN => Clause::OLD
]);
// => REPLACE ... RETURN OLD

Features

  • Dynamically builds an optimized REPLACE AQL query.
  • Supports bind variables to prevent injection.
  • Allows excluding specific attributes from the replacement document.
  • Supports returning OLD or NEW documents via Clause.
  • Integrates with PrepareDocumentTrait to prepare and normalize documents.
  • Uses BindTrait to manage AQL bind parameters.
Tags
see
https://docs.arangodb.com/stable/aql/high-level-operations/replace
PrepareDocumentTrait
BindTrait
ArangoTrait

Table of Contents

Methods

replace()  : object|null
Replaces an existing document in a collection with a new one.
update()  : object|null
Partially updates a document in the collection.
updateDate()  : object|null
Update a single date property in a document with the current date .
executeWriteOperation()  : object|null
The main internal function to update or replace a document in a collection.

Methods

replace()

Replaces an existing document in a collection with a new one.

public replace([array{doc?: array|object|null, key?: string|null, value?: mixed, binds?: array|null, excludes?: string[]|null, options?: array|string|object|null, prefix?: string|null, return?: string|null} $init = [] ]) : object|null

This operation removes all existing attributes of the document, except immutable system attributes (such as _key, _id, _rev), and sets the given attributes provided in $doc.

It uses an AQL query similar to:

FOR doc IN @@collection
  FILTER doc._key == @key
  REPLACE { ...fillableDocument, modified: DATE_ISO8601(DATE_NOW()) } IN @@collection
  RETURN NEW

Example usage:

$result = $this->replace
([
    Arango::DOC    => [ 'name' => 'Marc', 'city' => 'Marseille' ],
    Arango::VALUE  => '2531394',
    Arango::BINDS  => [ '@collection' => 'places' ],
]);

echo $result->name; // "Marc"
Parameters
$init : array{doc?: array|object|null, key?: string|null, value?: mixed, binds?: array|null, excludes?: string[]|null, options?: array|string|object|null, prefix?: string|null, return?: string|null} = []

The initialization options for the REPLACE operation.

Tags
throws
ArangoException

If the database request fails.

BindException

If an error occurs when preparing bind variables.

ContainerExceptionInterface

If the DI container fails.

DateInvalidTimeZoneException
DateMalformedStringException
DependencyException

If a dependency cannot be resolved via DI.

Error409
NotFoundException

If a dependency is missing in the container.

NotFoundExceptionInterface

If the DI container cannot locate a dependency.

ReflectionException

If reflection fails when preparing the document.

UnsupportedOperationException
Throwable
Return values
object|null —

The replaced document, or null if no matching document was found.

update()

Partially updates a document in the collection.

public update([array{doc?: array|object|null, key?: string|null, excludes?: string[]|null, value?: mixed, prefix?: string|null, binds?: array|null, options?: array|string|object|null, return?: string|null} $init = [] ]) : object|null

This method generates and executes an AQL UPDATE operation on the targeted document. Only the attributes specified in the doc array or object are modified; any other attributes in the existing document remain unchanged. Immutable system attributes (such as _key, _id, _rev) are never overwritten.

AQL Syntax

// Update using a key:
UPDATE @key WITH { ...updatedAttributes } IN @@collection [OPTIONS {...}]

// Update using a FOR ... FILTER clause:
FOR doc IN @@collection
  FILTER doc._key == @key
  UPDATE doc WITH { ...updatedAttributes } IN @@collection [OPTIONS {...}]
  RETURN NEW

Initialization Options ($init)

Parameters
$init : array{doc?: array|object|null, key?: string|null, excludes?: string[]|null, value?: mixed, prefix?: string|null, binds?: array|null, options?: array|string|object|null, return?: string|null} = []

Examples*

// 1. Update a document by key:
$result = $this->update
([
    Arango::DOC   => [ 'name' => 'Marc' ],
    Arango::VALUE => '2531394',
    Arango::BINDS => [ '@collection' => 'places' ]
]);

// 2. Update excluding certain fields:
$result = $this->update
([
    Arango::DOC      => [ 'name' => 'Marc', 'created' => '...' ],
    Arango::EXCLUDES => [ 'created' ],
    Arango::VALUE    => '2531394'
]);

// 3. Update and return the OLD document:
$result = $this->update
([
    Arango::DOC    => [ 'name' => 'Marc' ],
    Arango::VALUE  => '2531394',
    Arango::RETURN => Clause::OLD
]);
Tags
throws
ArangoException

If the database request fails.

BindException

If an error occurs while binding variables.

ContainerExceptionInterface

If the DI container throws an exception.

DateInvalidTimeZoneException
DateMalformedStringException
DependencyException

If a DI dependency cannot be resolved.

Error409
NotFoundException

If a DI dependency is missing.

NotFoundExceptionInterface

If the DI container cannot locate a dependency.

ReflectionException

If reflection fails when preparing the document.

UnsupportedOperationException
Throwable
Return values
object|null —

The updated document, or null if no document matched the key.

updateDate()

Update a single date property in a document with the current date .

public updateDate([array<string|int, mixed> $init = [] ][, string $property = Schema::MODIFIED ]) : object|null

By default, it updates the modified property with the current timestamp.

Parameters
$init : array<string|int, mixed> = []

Additional options like binds, return clause, etc.

$property : string = Schema::MODIFIED

The document property to update (default: Schema::MODIFIED).

Tags
throws
ArangoException
BindException
ContainerExceptionInterface
DateInvalidTimeZoneException
DateMalformedStringException
DependencyException
NotFoundException
NotFoundExceptionInterface
ReflectionException
Throwable
Return values
object|null —

The updated document.

executeWriteOperation()

The main internal function to update or replace a document in a collection.

protected executeWriteOperation(array{value?: mixed|null, doc?: array|object|string|null, key?: string|null, prefix?: string|null, binds?: array|null, excludes?: string[]|null, options?: array|string|object|null, return?: string|null, debug?: bool|null} $init[, string $operation = Operation::UPDATE ]) : object|null

This method builds and executes an AQL UPDATE or REPLACE query for a given document. It supports bind variables, exclusion of certain fields, custom options, and returning either the NEW or OLD document after the operation. Supported $init options*

Parameters
$init : array{value?: mixed|null, doc?: array|object|string|null, key?: string|null, prefix?: string|null, binds?: array|null, excludes?: string[]|null, options?: array|string|object|null, return?: string|null, debug?: bool|null}
$operation : string = Operation::UPDATE

The type of operation: Operation::UPDATE or Operation::REPLACE.

Tags
throws
InvalidArgumentException

If $operation is not UPDATE or REPLACE.

ArangoException

If the database request fails.

BindException

If an error occurs while binding variables.

ContainerExceptionInterface

If the DI container throws an exception.

DateInvalidTimeZoneException

If a date/time operation fails due to an invalid timezone.

DateMalformedStringException

If a date/time string cannot be parsed.

DependencyException

If a DI dependency cannot be resolved.

NotFoundException

If a DI dependency is missing.

NotFoundExceptionInterface

If the DI container cannot locate a dependency.

ReflectionException

If reflection fails when preparing the document.

Return values
object|null —

Returns the updated or replaced document, or null if no matching document was found.

On this page

Search results