Oihana PHP

DocumentsModel extends CountModel, DeleteModel, ExistModel, GetModel, InsertModel, LastModel, ListModel, ReplaceModel, StreamModel, UpdateModel, UpdateDateModel, UpsertModel, TruncateModel

Interface DocumentsModel

Defines a complete contract for managing documents in a storage system.

This interface groups together multiple CRUD-like operations and other database-related actions. It abstracts the logic for querying, inserting, updating, replacing, deleting, listing, truncating, and upserting documents in a storage backend (e.g., ArangoDB, OpenEdge SQL, etc.).

All inherited interfaces expose methods with a similar signature, accepting an optional $init array of options and returning various types depending on the context.

Supported Operations:

  • Counting documents.
  • Checking existence of documents.
  • Retrieving single or multiple documents.
  • Inserting new documents.
  • Updating or replacing existing documents.
  • Upserting documents (insert or update depending on existence).
  • Deleting documents.
  • Listing documents based on criteria.
  • Fetching the last document matching specific conditions.
  • Truncating the underlying storage (removing all documents).

Because it aggregates every single-purpose interface of this namespace, a DocumentsModel is the type to depend on whenever a service needs the full CRUD surface of a collection rather than one isolated capability.

Tags
example 
use oihana\models\interfaces\DocumentsModel;

function syncUser( DocumentsModel $users, array $payload ) : mixed
{
    $key = $payload[ 'key' ] ?? null ;

    return $users->exist( [ 'key' => $key ] )
         ? $users->update( [ 'key' => $key, 'document' => $payload ] )
         : $users->insert( [ 'document' => $payload ] ) ;
}
author

Marc Alcaraz

since
1.0.0

Table of Contents

Methods

count()  : int
Returns the number of documents matching the given options.
delete()  : null|array<string|int, mixed>|object
Deletes a document, or a set of documents, in the model.
exist()  : bool
Indicates whether a document matching the given options exists.
get()  : mixed
Returns a single document matching the given options.
insert()  : mixed
Inserts a new document into the model.
last()  : mixed
Returns the last document in the model.
list()  : array<string|int, mixed>
Returns a collection of items from the model.
replace()  : mixed
Replaces an existing document in the model.
stream()  : Generator<string|int, mixed>
Streams documents from the model.
truncate()  : mixed
Truncates the collection and removes all documents.
update()  : mixed
Updates an existing document in the model.
updateDate()  : mixed
Updates a single date property in a document with the current date.
upsert()  : mixed
Inserts or updates a document depending on whether it already exists.

Methods

count()

Returns the number of documents matching the given options.

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

Operation options driving the count, e.g. filtering conditions, bind variables (binds) or a precompiled query. An empty array counts every document.

Tags
example 
use oihana\models\interfaces\CountModel;

class UserModel implements CountModel
{
    public function count( array $init = [] ) : int
    {
        // run a COUNT query using $init['conditions'] / $init['binds']
        return 128 ;
    }
}

$model = new UserModel() ;

$total  = $model->count() ;                                  // every user
$active = $model->count( [ 'conditions' => 'doc.active == true' ] ) ;
Return values
int —

The number of matching documents (0 when none match).

delete()

Deletes a 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> = []

Operation options identifying what to delete, typically a key/id, a set of conditions with their binds and an optional return clause.

Tags
example 
use oihana\models\interfaces\DeleteModel;

class UserModel implements DeleteModel
{
    public function delete( array $init = [] ) : null|array|object
    {
        return $this->store->remove( $init[ 'key' ] ?? null ) ;
    }
}

$model   = new UserModel() ;
$removed = $model->delete( [ 'key' => 'users/42' ] ) ;
Return values
null|array<string|int, mixed>|object —

The deleted document(s) when the implementation returns them, otherwise null.

exist()

Indicates whether a document matching the given options exists.

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

Operation options identifying the document to test, typically a key/id value, a set of conditions and their binds.

Tags
example 
use oihana\models\interfaces\ExistModel;

class UserModel implements ExistModel
{
    public function exist( array $init = [] ) : bool
    {
        return isset( $init[ 'key' ] ) && $this->store->has( $init[ 'key' ] ) ;
    }
}

$model = new UserModel() ;

if ( $model->exist( [ 'key' => 'users/42' ] ) )
{
    // safe to fetch or update
}
Return values
bool —

true if at least one matching document exists, otherwise false.

get()

Returns a single document matching the given options.

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

Operation options identifying the document to fetch, typically a key/id value, optional conditions with their binds and projection settings.

Tags
example 
use oihana\models\interfaces\GetModel;

class UserModel implements GetModel
{
    public function exist( array $init = [] ) : bool { return true ; }

    public function get( array $init = [] ) : mixed
    {
        return $this->store->find( $init[ 'key' ] ?? null ) ;
    }
}

$model = new UserModel() ;
$user  = $model->get( [ 'key' => 'users/42' ] ) ;
Return values
mixed —

The resolved document (commonly an array or object), or a null/empty value when nothing matches, depending on the implementation.

insert()

Inserts a new document into the model.

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

Operation options carrying the data to insert, typically the document payload, optional binds and a return clause describing what the call should yield.

Tags
example 
use oihana\models\interfaces\InsertModel;

class UserModel implements InsertModel
{
    public function insert( array $init = [] ) : mixed
    {
        return $this->store->add( $init[ 'document' ] ?? [] ) ;
    }
}

$model = new UserModel() ;
$user  = $model->insert( [ 'document' => [ 'name' => 'Alice' ] ] ) ;
Return values
mixed —

The inserted document (or its identifier/result), depending on the implementation.

last()

Returns the last document in the model.

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

Operation options driving the lookup, typically the sort field used to determine "last" (default: the modified property), optional conditions and binds.

Tags
example 
use oihana\models\interfaces\LastModel;

class LogModel implements LastModel
{
    public function exist( array $init = [] ) : bool { return true ; }

    public function last( array $init = [] ) : mixed
    {
        return $this->store->latest( $init[ 'sort' ] ?? 'modified' ) ;
    }
}

$model      = new LogModel() ;
$lastEntry  = $model->last() ;                       // by 'modified'
$lastByDate = $model->last( [ 'sort' => 'created' ] ) ;
Return values
mixed —

The last matching document, or a null/empty value when the collection is empty, depending on the implementation.

list()

Returns a collection of items from the model.

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

Retrieves all documents as an array. For large datasets, consider using a streaming approach (e.g., StreamModel) to avoid high memory usage.

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

Operation options scoping the result set, typically conditions with their binds, a sort clause and pagination bounds (offset/limit). An empty array lists every document.

Tags
example 
use oihana\models\interfaces\ListModel;

class UserModel implements ListModel
{
    public function list( array $init = [] ) : array
    {
        return $this->store->query( $init[ 'conditions' ] ?? null, $init[ 'sort' ] ?? null ) ;
    }
}

$model = new UserModel() ;

$all    = $model->list() ;
$active = $model->list( [ 'conditions' => 'doc.active == true', 'sort' => 'name' ] ) ;
Return values
array<string|int, mixed> —

An array of documents or items. The structure and type of each item depend on the model implementation.

replace()

Replaces an existing document in the model.

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

Operation options carrying the replacement, typically the target key/id, the full document payload, optional binds and a return clause.

Tags
example 
use oihana\models\interfaces\ReplaceModel;

class UserModel implements ReplaceModel
{
    public function replace( array $init = [] ) : mixed
    {
        return $this->store->set( $init[ 'key' ], $init[ 'document' ] ?? [] ) ;
    }
}

$model = new UserModel() ;
$user  = $model->replace( [ 'key' => 'users/42', 'document' => [ 'name' => 'Bob' ] ] ) ;
Return values
mixed —

The replaced document (or its result), depending on the implementation.

stream()

Streams documents from the model.

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

This method returns a generator that yields each document one at a time. It is useful for iterating over large collections efficiently, since documents are produced lazily instead of being loaded all at once like ListModel::list() does.

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

Operation options scoping the stream, typically conditions with their binds, a sort clause and a batch size. An empty array streams every document.

Tags
example 
use Generator;
use oihana\models\interfaces\StreamModel;

class UserModel implements StreamModel
{
    public function stream( array $init = [] ) : Generator
    {
        foreach ( $this->store->cursor( $init[ 'conditions' ] ?? null ) as $row )
        {
            yield $row ;
        }
    }
}

$model = new UserModel() ;

foreach ( $model->stream( [ 'conditions' => 'doc.active == true' ] ) as $user )
{
    // process one user at a time, constant memory
}
Return values
Generator<string|int, mixed> —

Yields each document in the collection. The type of document depends on the model implementation.

truncate()

Truncates the collection and removes all documents.

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

Operation options, e.g. flags forwarded to the storage engine. An empty array truncates with default settings.

Tags
example 
use oihana\models\interfaces\TruncateModel;

class CacheModel implements TruncateModel
{
    public function truncate( array $init = [] ) : mixed
    {
        return $this->store->clear() ;
    }
}

$model = new CacheModel() ;
$model->truncate() ; // empties the whole collection
Return values
mixed —

The truncation result, depending on the implementation (commonly a boolean, a count, or null).

update()

Updates an existing document in the model.

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

Operation options carrying the change to apply, typically the target key/id, the document patch to merge, optional binds and a return clause.

Tags
example 
use oihana\models\interfaces\UpdateModel;

class UserModel implements UpdateModel
{
    public function update( array $init = [] ) : mixed
    {
        return $this->store->patch( $init[ 'key' ], $init[ 'document' ] ?? [] ) ;
    }
}

$model = new UserModel() ;
$user  = $model->update( [ 'key' => 'users/42', 'document' => [ 'active' => false ] ] ) ;
Return values
mixed —

The updated document (or its result), depending on the implementation.

updateDate()

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

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

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

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

Operation options identifying the target document, typically a key/id, an explicit value to use instead of "now", optional binds and a return clause.

$property : string = Schema::MODIFIED

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

Tags
example 
use oihana\models\interfaces\UpdateDateModel;
use org\schema\constants\Schema;

class UserModel implements UpdateDateModel
{
    public function updateDate( array $init = [] , string $property = Schema::MODIFIED ) : mixed
    {
        return $this->store->touch( $init[ 'key' ] ?? null, $property, date( 'c' ) ) ;
    }
}

$model = new UserModel() ;

$model->updateDate( [ 'key' => 'users/42' ] ) ;                       // stamps `modified`
$model->updateDate( [ 'key' => 'users/42' ], Schema::DATE_PUBLISHED ) ; // stamps another field
Return values
mixed —

The updated document (or operation result), depending on the implementation.

upsert()

Inserts or updates a document depending on whether it already exists.

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

Operation options carrying the document and its lookup keys, typically the matching conditions/key, the document payload, optional binds and a return clause.

Tags
example 
use oihana\models\interfaces\UpsertModel;

class UserModel implements UpsertModel
{
    public function upsert( array $init = [] ) : mixed
    {
        return $this->store->upsert( $init[ 'key' ] ?? null, $init[ 'document' ] ?? [] ) ;
    }
}

$model = new UserModel() ;
$user  = $model->upsert( [ 'key' => 'users/42', 'document' => [ 'name' => 'Alice' ] ] ) ;
Return values
mixed —

The upserted document (or its result), depending on the implementation.

On this page

Search results