Oihana PHP Arango

DocumentsMethodsTrait uses trait:short, trait:short, trait:short, trait:short, trait:short, trait:short, trait:short, trait:short, trait:short, trait:short, trait:short, trait:short, trait:short, trait:short, trait:short

Table of Contents

Constants

ON_UPDATE_RELATIONS  : string = 'onUpdateRelations'
The 'onUpdateRelations' method name.

Methods

count()  : int
Count the number of documents in a collection.
delete()  : null|array<string|int, mixed>|object
Deletes an document or a set of documents in the model.
exist()  : bool
Checks for the existence of one or more documents based on their keys or specified attributes.
existByKey()  : bool
Check if a document exist with the specific key.
existIn()  : bool
Check if the given list of values exist in the collection.
explainList()  : ExplainResult
Explains the query that {@see list()} would run for the same `$init`, **without executing it**. Use it to check which indexes the list query actually uses, the optimizer rules that fire, and the estimated cost — straight from the same filter / facet / search / sort / pagination input.
facetCounts()  : array<string, array<int, object|array<string|int, mixed>>>
Returns per-value bucket counts for the requested facet dimensions.
get()  : object|null
Returns the specific item.
initializeDocumentsMethods()  : static
Initialize the Documents HTTP methods signals.
insert()  : object|null
Insert a new document into the collection.
last()  : mixed
Returns the last document in the Documents collection.
list()  : array<string|int, mixed>
Retrieves a list of documents from the collection with filtering, sorting, and pagination.
onUpdateRelations()  : void
Invoked when a document is inserted, replaced or updated in a Documents to update the document's relations (edges).
registerUpdateRelations()  : static
Register the onUpdateRelations callbacks to handles the insert/replace/update methods.
replace()  : object|null
Replaces an existing document in a collection with a new one.
repsert()  : array<string, mixed>|object|null
Repsert a document into the collection (replace or insert).
stream()  : Generator<string|int, mixed>
Retrieves documents as a generator stream from the collection with filtering, sorting, and pagination support.
truncate()  : bool
Truncates the collection.
unregisterUpdateRelations()  : static
Unregister the onUpdateRelations callbacks.
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 .
upsert()  : array<string, mixed>|object|null
Upsert a document into the collection (update or insert).
executeWriteOperation()  : object|null
The main internal function to update or replace a document in a collection.

Constants

ON_UPDATE_RELATIONS

The 'onUpdateRelations' method name.

public string ON_UPDATE_RELATIONS = 'onUpdateRelations'

Methods

count()

Count the number of documents in a collection.

public count([array{optimized?: array, binds?: array, active?: bool, facets?: array, search?: array, conditions?: array} $init = [] ]) : int

Supports both optimized (unfiltered) and filtered modes.

This method generates and executes an AQL query to return the total number of documents.

It supports two primary modes:

  1. Filtered Count (default) : Counts documents based on various criteria such as 'active' status, facets, general filters, and search terms. This mode constructs a more complex AQL query, example : RETURN LENGTH( FOR doc IN collection FILTER doc.active == [1|0] [ && facets ] [ && search ] [ && conditions ] RETURN 1 )

  2. Optimized Count (Unfiltered) : Provides a fast count of all documents in the collection, bypassing any filtering. Useful for quick total counts. RETURN LENGTH( collection )

Parameters
$init : array{optimized?: array, binds?: array, active?: bool, facets?: array, search?: array, conditions?: array} = []

An associative array of optional settings to define the counting behavior:

  • optimized (bool, optional): If true, a faster, unfiltered count of the entire collection is performed. If false (default), the method applies all specified filters.
  • binds (array<string, mixed>, optional): An array of AQL bind variables to be directly included in the query. Primarily used for filtered counts.
  • active (?bool, optional): Filters documents based on their 'active' status. Only applies if optimized is false. If true, only active documents are counted. If false, only inactive documents. If null (or not set), this filter is not applied.
  • facets (?array, optional): An array of conditions to apply as 'facets' for filtering. Only applies if optimized is false. Handled by prepareFacets().
  • filter (?array, optional): An array of general filter conditions to apply. Only applies if optimized is false. Handled by prepareFilter().
  • search (?array, optional): An array of search conditions to apply. Only applies if optimized is false. Handled by prepareSearch().
  • conditions (?array, optional): An array of additional AQL filter conditions to append to the query. Only applies if optimized is false.
Tags
throws
ArangoException

If there's an issue with the ArangoDB query execution.

BindException

If there's an error binding parameters to the AQL query.

ReflectionException

If a reflection error occurs (e.g., during internal AQL building).

DependencyException
NotFoundException
ContainerExceptionInterface
NotFoundExceptionInterface
example
$model->count() ; $model->count( [ Arango::OPTIMIZED => true ] ) ; $model->count( [ Arango::FACETS => [ ... ] , Arango::FILTER = [ ... ] ] ] ) ;
Return values
int —

The number of documents matching the criteria. Returns 0 if in mock mode.

delete()

Deletes an document or a set of documents in the model.

public delete([array<string|int, mixed> $init = [] ]) : null|array<string|int, mixed>|object
Parameters
$init : array<string|int, mixed> = []

The optional setting definition :

  • value (mixed) : The value of the key to identify the document to remove in the collection.
  • key (string|null) : The key attribute to target (default _key)
  • prefix (string|null) : The prefix document of the key (default use "doc" -> "doc.key" )
  • binds (array|null) : The prefix document of the key (default use "doc" -> "doc.key" )
Tags
throws
ArangoException
BindException
ContainerExceptionInterface
DependencyException
NotFoundException
NotFoundExceptionInterface
ReflectionException
UnsupportedOperationException
Throwable
Return values
null|array<string|int, mixed>|object

exist()

Checks for the existence of one or more documents based on their keys or specified attributes.

public exist([array{value?: int|string|(int|string)[], key?: null|string, prefix?: null|string, match?: null|string, conditions?: null|array} $init = [] ]) : bool

This method constructs and executes an AQL query to determine if documents matching the provided criteria exist within the collection.

The behavior for multiple values depends on the $match parameter, allowing you to check if any, all, or none of the specified values exist.

Generated the AQL query : RETURN LENGTH(FOR doc IN @@collection FILTER doc._key IN @values [ && ...additionalConditions ] RETURN 1)

Parameters
$init : array{value?: int|string|(int|string)[], key?: null|string, prefix?: null|string, match?: null|string, conditions?: null|array} = []

An associative array of optional settings to define the search criteria:

  • value : The single value or an array of values to search for. These values will be matched against the document key or the attribute specified by `key`.
  • match : Determines the matching strategy when multiple `value`s are provided. Uses constants from `ArrayComparator` enumeration.
    • `ArrayComparator::ALL` (default): Returns `true` only if *all* specified `value`s exist as documents.
    • `ArrayComparator::ANY`: Returns `true` if *at least one* of the specified `value`s exists as a document.
  • key : The document attribute to target for the existence check (e.g., `_key`, `name`, `userId`). Defaults to `_key`.
  • prefix : The document alias used in the AQL query (e.g., "doc" in `doc._key`). Defaults to "doc".
  • conditions : An array of additional AQL filter conditions to append to the query.
Tags
throws
ArangoException

If there's an issue with the ArangoDB query execution.

BindException

If there's an error binding parameters to the AQL query.

ReflectionException

If a reflection error occurs (e.g., during internal AQL building).

DependencyException
NotFoundException
ContainerExceptionInterface
NotFoundExceptionInterface
Return values
bool —

True of the value exist in the model.

existByKey()

Check if a document exist with the specific key.

public existByKey(string $key[, array<string|int, mixed> $init = [] ]) : bool
Parameters
$key : string

The key index of the object resource to target.

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

The optional setting definition.

Tags
throws
ArangoException
BindException
ContainerExceptionInterface
DependencyException
NotFoundException
NotFoundExceptionInterface
ReflectionException
Return values
bool —

True of the value exist in the model.

existIn()

Check if the given list of values exist in the collection.

public existIn(array<string|int, mixed> $values[, string $match = ArrayComparator::ALL ][, array<string|int, mixed> $init = [] ]) : bool
Parameters
$values : array<string|int, mixed>
$match : string = ArrayComparator::ALL

Determines the matching strategy when multiple values are provided. Uses constants from ArrayComparator enumeration.

  • `ArrayComparator::ALL` (default): Returns `true` only if *all* specified `value`s exist as documents.
  • `ArrayComparator::ANY`: Returns `true` if *at least one* of the specified `value`s exists as a document.
$init : array<string|int, mixed> = []
Tags
throws
ArangoException
BindException
ContainerExceptionInterface
DependencyException
NotFoundException
NotFoundExceptionInterface
ReflectionException
Return values
bool

explainList()

Explains the query that {@see list()} would run for the same `$init`, **without executing it**. Use it to check which indexes the list query actually uses, the optimizer rules that fire, and the estimated cost — straight from the same filter / facet / search / sort / pagination input.

public explainList([array<string|int, mixed> $init = [] ]) : ExplainResult
Parameters
$init : array<string|int, mixed> = []

The same input array accepted by list().

Tags
throws
ArangoException
BindException
ConstantException
ContainerExceptionInterface
DependencyException
NotFoundException
NotFoundExceptionInterface
ReflectionException
UnsupportedOperationException
ValidationException
see
list()

For the executed counterpart.

Return values
ExplainResult —

The typed execution plan.

facetCounts()

Returns per-value bucket counts for the requested facet dimensions.

public facetCounts([array<string|int, mixed> $init = [] ]) : array<string, array<int, object|array<string|int, mixed>>>
Parameters
$init : array<string|int, mixed> = []

The list options. Arango::FACET_COUNTS holds the facet keys to count; the other keys (active, facets, filter, search, conditions) define the filtered set.

Tags
throws
ArangoException
BindException
ConstantException
ContainerExceptionInterface
DependencyException
NotFoundException
NotFoundExceptionInterface
ReflectionException
UnsupportedOperationException
ValidationException
Return values
array<string, array<int, object|array<string|int, mixed>>> —

A dimension => [ { value, count }, ... ] map (empty when nothing countable).

get()

Returns the specific item.

public get([array<string|int, mixed> $init = [] ]) : object|null
Parameters
$init : array<string|int, mixed> = []

The optional setting definition :

  • value (mixed ) : The value to find in the model.
  • key (?string) : The key attribute to target (default _key)
  • prefix (?string) : The prefix document of the key (default use "doc" -> "doc.key" )
  • binds : The default bind variables.
  • conditions : The default conditions to passed-in the AQL query.
  • extraQuery : The extra query to inject in the AQL query.
  • active : The optional active property.
  • fields (?array<string>, optional): An array of specific fields to return for each document. If not provided, all document fields are returned. Handled by returnFields().
  • skin (?, optional): The skin to apply on the result document.
Tags
throws
ArangoException

If there's an issue with the ArangoDB query execution.

BindException

If there's an error binding parameters to the AQL query.

ContainerExceptionInterface
NotFoundExceptionInterface
ReflectionException

If a reflection error occurs (e.g., during internal AQL building).

Return values
object|null —

The specific item.

initializeDocumentsMethods()

Initialize the Documents HTTP methods signals.

public initializeDocumentsMethods() : static
Return values
static

insert()

Insert a new document into the collection.

public insert([array{binds?: array|null, conditions?: array|null, debug?: bool|null, doc?: null|array|object|string, excludes?: array|null} $init = [] ]) : object|null
Parameters
$init : array{binds?: array|null, conditions?: array|null, debug?: bool|null, doc?: null|array|object|string, excludes?: array|null} = []

The parameters to passed-in the function.

  • doc : The document to insert in the collection.
  • excludes : The list of all attributes to excludes in the new document
  • binds The default variables to binds.
  • relations The edges relations definitions to link after the insertion
Tags
throws
ArangoException
BindException
ContainerExceptionInterface
DateInvalidTimeZoneException
DateMalformedStringException
DependencyException
Error409
NotFoundException
NotFoundExceptionInterface
ReflectionException
UnsupportedOperationException
Throwable
Return values
object|null

last()

Returns the last document in the Documents collection.

public last([array<string|int, mixed> $init = [] ]) : mixed

By default, the method search the last 'modified' document.

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

An associative array of optional settings to define the query:

return mixed The last item in the collection (By default modified).

  • **`bindVars`** (`array`, optional) : Custom bind variables.
  • **`property`** (`string`, optional) : The property used for sorting (default: `Schema::MODIFIED`).
  • **`fields`** (`array`, optional) : Fields to return (handled by `returnFields()`).
Tags
throws
ArangoException

If there's an issue with the ArangoDB query execution.

BindException

If there's an error binding parameters to the AQL query.

ContainerExceptionInterface
DependencyException
NotFoundException
NotFoundExceptionInterface
ReflectionException

If a reflection error occurs (e.g., during internal AQL building).

list()

Retrieves a list of documents from the collection with filtering, sorting, and pagination.

public list([array<string|int, mixed> $init = [] ]) : array<string|int, mixed>

This is the main entry point for fetching multiple documents from an ArangoDB collection. It constructs an AQL query using buildListQuery(), executes it, and returns all matching documents loaded into memory. Each document is processed through schema mapping (if configured) and transformation via the alter() method.

When to Use:

  • When you need all results in memory for further processing
  • For small to medium result sets (< 10,000 documents)
  • When you need to count, sort, or filter results in PHP
  • For API responses that return complete datasets

Performance Considerations:

  • All documents are loaded into memory at once
  • For large datasets (> 10,000 documents), consider using stream() instead
  • Use limit and offset for pagination to control memory usage
  • Use fields to reduce data transfer by selecting only needed fields

Generated AQL Query Structure:

FOR doc IN @@collection
  FILTER doc.active == [1|0] [&& facets] [&& filter] [&& search] [&& conditions]
  SORT field1 ASC, field2 DESC
  LIMIT offset, limit
  RETURN { ...fields }

Usage Examples:

Basic usage:

$documents = $model->list();
// Returns all documents from the collection

With filtering and pagination:

$documents = $model->list([
    'active' => true,
    'filter' => ['status' => 'published'],
    'limit'  => 50,
    'offset' => 0
]);
// Returns first 50 active, published documents

Complex query with all features:

$documents = $model->list([
    'active'  => true,
    'facets'  => ['category' => 'electronics'],
    'filter'  => ['price' => ['$gte' => 100]],
    'search'  => ['title' => 'laptop'],
    'sort'    => ['priority' => 'DESC', 'createdAt' => 'ASC'],
    'limit'   => 100,
    'offset'  => 0,
    'fields'  => ['_key', 'title', 'price', 'stock'],
    'skin'    => 'api'
]);

With custom binds:

$documents = $model->list([
    'conditions' => ['doc.price >= @minPrice', 'doc.stock > 0'],
    'binds'      => ['minPrice' => 500]
]);
Parameters
$init : array<string|int, mixed> = []

Configuration array with optional parameters:

Query Binding:*

  • binds (array<string, mixed>, optional) Additional AQL bind variables to include in the query. Merged with auto-generated bind variables. Default: []

Pagination:*

  • limit (int, optional) Maximum number of documents to return. Set to 0 for no limit. When > 0, enables full count calculation for pagination metadata. Default: 0

  • offset (int, optional) Number of documents to skip before returning results. Useful for pagination when combined with limit. Default: 0

Filtering:*

  • active (?bool, optional) Filter by active status. true returns only active documents, false returns only inactive documents, null ignores this filter. Default: null

  • facets (?array, optional) Array of facet conditions for categorical filtering. Processed by prepareFacets(). Example: ['category' => 'books', 'language' => 'en'] Default: null

  • conditions (?array, optional) Array of custom filter conditions. When provided, this overrides the automatic combination of active/facets/filter/search. Example: ['doc.price > 100', 'doc.stock > 0'] Default: null

  • filter (?array, optional) Array of general filter conditions. Processed by prepareFilter(). Example: ['status' => 'published', 'featured' => true] Default: null

  • search (?array, optional) Array of search conditions for text-based filtering. Processed by prepareSearch(). Example: ['title' => 'search term', 'tags' => 'important'] Default: null

Sorting:*

  • sort (?array, optional) Array defining sort criteria. Keys are field names, values are 'ASC' or 'DESC'. Processed by prepareSort(). Example: ['createdAt' => 'DESC', 'title' => 'ASC'] Default: null

Field Selection:*

  • fields (?array<string>, optional) Array of specific field names to return. Supports dot notation. If not provided, all document fields are returned. Processed by returnFields(). Example: ['_key', 'title', 'author.name', 'publishedAt'] Default: null (all fields)

Output Transformation:*

  • skin (?string, optional) Name of the skin/transformation to apply to result documents. Applied during the alter() phase. Example: 'summary', 'detailed' Default: null

Query Variables:*

  • variables (?array, optional) Additional AQL LET statements to declare in the query. Default: []

Debugging:*

  • debug (?bool, optional) Enable query debugging. When true, logs the AQL query and bind variables. Default: false
Tags
throws
ArangoException

If there's an error during ArangoDB query execution, such as:

  • Invalid AQL syntax in the generated query
  • Collection not found or not accessible
  • Connection timeout or network issues
  • Insufficient permissions
  • Query timeout (exceeded max execution time)
BindException

If there's an error binding parameters to the AQL query, such as:

  • Invalid bind variable names (reserved keywords, special characters)
  • Type mismatch in bind values
  • Collection binding errors
ConstantException
ContainerExceptionInterface

If there's an error accessing the dependency injection container while resolving services needed for query execution or result processing

DependencyException
NotFoundException
NotFoundExceptionInterface

If a required service is not found in the dependency injection container

ReflectionException

If a reflection error occurs during processing, such as:

  • Schema class not found or not accessible
  • Invalid schema structure
  • Property hydration errors
  • Method invocation failures during alter()
UnsupportedOperationException
ValidationException
see
buildListQuery()

For the query construction logic

getDocuments()

For the underlying execution and transformation

stream()

For memory-efficient streaming alternative

foundRows()

For getting total count without limit (when limit is set)

Return values
array<string|int, mixed> —

An array of matching documents. Each document is:

  • Retrieved from ArangoDB based on the query
  • Mapped to the configured schema class (if set via $this->schema)
  • Transformed via the alter() method (applies skins, conversions, etc.)

Returns an empty array if:

  • No documents match the query criteria
  • The collection is empty
  • All matching documents are filtered out by conditions

Example Return Structure:*

[
    0 => ProductSchema {
        _key: 'product_001',
        title: 'Gaming Laptop',
        price: 1299.99,
        stock: 5
    },
    1 => ProductSchema {
        _key: 'product_002',
        title: 'Office Laptop',
        price: 899.99,
        stock: 12
    }
]

onUpdateRelations()

Invoked when a document is inserted, replaced or updated in a Documents to update the document's relations (edges).

public onUpdateRelations(Payload $payload) : void
Parameters
$payload : Payload

The payload notice.

Tags
throws
BindException
ContainerExceptionInterface
DateInvalidTimeZoneException
DateMalformedStringException
DependencyException
Error409
ArangoException
NotFoundException
NotFoundExceptionInterface
ReflectionException
UnsupportedOperationException
Throwable

registerUpdateRelations()

Register the onUpdateRelations callbacks to handles the insert/replace/update methods.

public registerUpdateRelations() : static
Return values
static

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.

repsert()

Repsert a document into the collection (replace or insert).

public repsert([array<string, mixed> $init = [] ]) : array<string, mixed>|object|null
Parameters
$init : array<string, mixed> = []

The optional parameters to passed-in the function.

Detail of the options :

  • binds : The binding variables to use in the aql connector.
  • collection : The name of the collection or use the collection property of the model.
  • filter : The alternative filterExpression, this syntax for UPSERT operations allows you to use more flexible filter conditions beyond equality matches to look up documents.
  • search : The 'searchExpression' contains the document to be looked for. It must be an object literal (UPSERT { : , ... } ...) without dynamic attribute names. In case no such document can be found in collection, a new document is inserted into the collection as specified in the insertExpression.
  • insert : The document to insert in the collection if the document not exist.
  • replace : The document to replace in the collection.
  • overwrite : The overwriting mode "REPLACE" or "UPDATE" (default)
  • options : The optional upsert options definition array or object.
Tags
throws
ArangoException
BindException
ContainerExceptionInterface
DateInvalidTimeZoneException
DateMalformedStringException
DependencyException
NotFoundException
NotFoundExceptionInterface
ReflectionException
UnsupportedOperationException
Return values
array<string, mixed>|object|null

stream()

Retrieves documents as a generator stream from the collection with filtering, sorting, and pagination support.

public stream([array<string|int, mixed> $init = [] ]) : Generator<string|int, mixed>

This method provides memory-efficient iteration over large result sets by yielding documents one at a time instead of loading them all into memory. Each document is fully processed (schema mapping and alter() transformation) before being yielded.

Key Benefits:

  • Memory Efficient: Only one document in memory at a time
  • Early Processing: Start processing results before the query completes
  • Large Datasets: Handle millions of documents without memory issues
  • Full Feature Set: Same filtering, sorting, and pagination as list()

Generated AQL Query Structure:

FOR doc IN @@collection
  FILTER doc.active == [1|0] [&& facets] [&& search] [&& conditions]
  SORT field1 ASC, field2 DESC
  LIMIT offset, limit
  RETURN { ...fields }

Usage Example:

// Process large dataset efficiently
foreach ($model->stream(['limit' => 10000]) as $document) {
    // Process one document at a time
    processDocument($document);
}

// With complex filtering
$generator = $model->stream([
    'active' => true,
    'filter' => ['status' => 'published'],
    'search' => ['title' => 'PHP'],
    'sort'   => ['createdAt' => 'DESC'],
    'limit'  => 1000,
    'offset' => 0
]);
Parameters
$init : array<string|int, mixed> = []

Configuration array with optional parameters:

Query Binding:*

  • binds (array<string, mixed>, optional) Additional AQL bind variables to include in the query. Default: []

Pagination:*

  • limit (int, optional) Maximum number of documents to return. Set to 0 for no limit. Default: 0

  • offset (int, optional) Number of documents to skip before returning results. Useful for pagination when combined with limit. Default: 0

Filtering:*

  • active (?bool, optional) Filter by active status. true returns only active documents, false returns only inactive documents, null ignores this filter. Default: null

  • facets (?array, optional) Array of facet conditions for filtering. Processed by prepareFacets(). Example: ['category' => 'books', 'year' => 2024] Default: null

  • conditions (?array, optional) Array of custom filter conditions. When provided, this overrides the automatic combination of active/facets/filter/search conditions. Default: null

  • filter (?array, optional) Array of general filter conditions. Processed by prepareFilter(). Example: ['status' => 'published', 'author.verified' => true] Default: null

  • search (?array, optional) Array of search conditions for text-based filtering. Processed by prepareSearch(). Example: ['title' => 'search term', 'description' => 'keyword'] Default: null

Sorting:*

  • sort (?array, optional) Array defining sort criteria. Keys are field names, values are 'ASC' or 'DESC'. Processed by prepareSort(). Example: ['createdAt' => 'DESC', 'title' => 'ASC'] Default: null

Field Selection:*

  • fields (?array<string>, optional) Array of specific field names to return for each document. If not provided, all document fields are returned. Processed by returnFields(). Example: ['_key', 'title', 'author.name', 'publishedAt'] Default: null (all fields)

Output Transformation:*

  • skin (?string, optional) Name of the skin/transformation to apply to result documents. The skin is applied during the alter() phase. Default: null

Query Variables:*

  • variables (?array, optional) Additional AQL variables to declare in the query (LET statements). Default: []

Debugging:*

  • debug (?bool, optional) Enable query debugging. When true, logs the generated AQL query and bind variables via debugQuery(). Default: false
Tags
throws
ArangoException

If there's an error during ArangoDB query execution, such as:

  • Invalid AQL syntax
  • Collection not found
  • Connection issues
  • Query timeout
BindException

If there's an error binding parameters to the AQL query, such as:

  • Invalid bind variable names
  • Type mismatch in bind values
  • Reserved keyword usage
ConstantException
ContainerExceptionInterface

If there's an error accessing the dependency injection container

DependencyException
NotFoundExceptionInterface

If a required service is not found in the dependency injection container

NotFoundException
UnsupportedOperationException
ReflectionException

If a reflection error occurs during internal processing, such as:

  • Schema class not found
  • Invalid schema structure
  • Property access errors during hydration
see
list()

For loading all documents into memory at once

buildListQuery()

For the query construction logic

streamDocuments()

For the underlying generator implementation

Return values
Generator<string|int, mixed> —

A PHP generator that yields documents one by one. Each yielded document has already been processed through schema mapping (if configured) and the alter() transformation method.

truncate()

Truncates the collection.

public truncate([array{collection: null|string} $init = [] ]) : bool

Warning: the method removes all documents.

Parameters
$init : array{collection: null|string} = []
Return values
bool

unregisterUpdateRelations()

Unregister the onUpdateRelations callbacks.

public unregisterUpdateRelations() : static
Return values
static

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.

upsert()

Upsert a document into the collection (update or insert).

public upsert([array<string, mixed> $init = [] ]) : array<string, mixed>|object|null
Parameters
$init : array<string, mixed> = []

The optional parameters to passed-in the function.

Detail of the options :

  • binds : The binding variables to use in the aql connector.
  • collection : The name of the collection or use the collection property of the model.
  • filter : The alternative filterExpression, this syntax for UPSERT operations allows you to use more flexible filter conditions beyond equality matches to look up documents.
  • search : The 'searchExpression' contains the document to be looked for. It must be an object literal (UPSERT { : , ... } ...) without dynamic attribute names. In case no such document can be found in collection, a new document is inserted into the collection as specified in the insertExpression.
  • insert : The document to insert in the collection if the document not exist.
  • update : The document to update or replace in the collection.
  • overwrite : The overwriting mode "REPLACE" or "UPDATE" (default)
  • options : The optional upsert options definition array or object.
Tags
throws
ArangoException
BindException
ContainerExceptionInterface
DateInvalidTimeZoneException
DateMalformedStringException
DependencyException
NotFoundException
NotFoundExceptionInterface
ReflectionException
UnsupportedOperationException
Return values
array<string, mixed>|object|null

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