AbstractMongoDao<`T`>

Abstract MongoDB DAO Service

abstract class AbstractMongoDao<T> extends MongoDb implements EntityRepo<T>, DbRefResolver<T>, PublisherAware

use MongoHelper

use Publishing

Copyright: 2015-2016 Appertly

License: Apache-2.0

Constructors / Destructors

Public
Returns	Signature and Description
`void`	`__construct`(`Manager $manager`, `string $collection`, `?ConstMap<string,mixed> $options = null`) Creates a new AbstractMongoDao.

Instance Methods

Public
Returns	Signature and Description
`int`	`countAll`(`ConstMap<string,mixed> $criteria`) Counts several records by some arbitrary criteria.
`Iterator`<`T`>	`findAll`(`ConstMap<string,mixed> $criteria`, `?Pagination $pagination = null`, `?bool $totalCount = false`) Finds several records by some arbitrary criteria.
`?T`	`findById`(`mixed $id`) Gets a single document by ID.
`?T`	`findOne`(`ConstMap<string,mixed> $criteria`) Finds a single record by some arbitrary criteria.
`T`	`get`(`mixed $id`) Gets a single document by ID, throwing an exception if it's not found.
`Traversable`<`T`>	`getAll`(`ConstVector<mixed> $ids`) Gets several documents by ID.
`ImmMap`<`string`,`T`>	`getInstanceMap`(`Traversable<T> $entities`) Gets a Map that relates identifier to instance
`string`	`getType`() Gets the type of entity produced, mainly for ACL reasons.
`bool`	`isResolvable`(`string $ref`) Gets whether or not this class supports the reference type.
`?T`	`resolve`(`DbRef $ref`) Resolves a MongoDB DbRef.
`Traversable`<`T`>	`resolveAll`(`Traversable<DbRef> $refs`) Resolves a MongoDB DbRef.

Protected
Returns	Signature and Description
`WriteResult`	`doCreate`(`ConstMap<string,mixed> $record`) Creates a record.
`WriteResult`	`doDelete`(`mixed $id`) Deletes a record.
`WriteResult`	`doPersist`(`Persistable $record`) Creates a record using a MongoDB `Persistable`.
`WriteResult`	`doUpdate`(`mixed $id`, `ConstMap<string,Map<string,mixed>> $operations`, `?int $version = null`) Updates a record.
`?WriteResult`	`doUpdateModifiable`(`Modifiable $entity`, `?int $version = null`) Updates a record.
`Ta`	`ensure`<`Ta`>(`mixed $id`, `?Ta $document`) Makes sure a document isn't null.
`?T`	`getFromCache`(`string $id`) Gets an entry from the cache
`?T`	`maybeCache`(`?T $entity`) Possibly add the entity to the cache.
`Traversable`<`T`>	`maybeCacheAll`(`Iterator<T> $entities`) Possibly add entities to the cache.
`UTCDateTime`	`now`() Gets the current time.
`?UTCDateTime`	`toDate`(`mixed $date`) Tries to parse a date.
`ObjectID`	`toId`(`mixed $id`) Transforms a literal into a MongoDB ObjectId.
`ConstVector`<`ObjectID`>	`toIds`(`ConstVector<mixed> $ids`) Transforms literals into MongoDB ObjectIds.

Method Details

__construct

public function __construct(Manager $manager, string $collection, ?ConstMap<string,mixed> $options = null)

Creates a new AbstractMongoDao.

Current accepted configuration values:

versioned – Whether to enforce optimistic locking via a version field (default: true)
caching – Whether to cache entities by ID (default: true)
typeMapRoot – The type used to unserialize BSON root documents
typeMapDocument – The type used to unserialize BSON nested documents
readPreference – Must be a MongoDB\Driver\ReadPreference
writeConcern – Must be a MongoDB\Driver\WriteConcern

As for the typeMap options, you can see Deserialization from BSON for more information.

Parameters
Name	Type	Description
`$manager`	`Manager`	The MongoDB Manager
`$collection`	`string`	The collection to wrap
`$options`	`?ConstMap`<`string`,`mixed`>	Map of configuration values

countAll

public function countAll(ConstMap<string,mixed> $criteria)

Counts several records by some arbitrary criteria.

Since: 0.6.0

Parameters
Name	Type	Description
`$criteria`	`ConstMap`<`string`,`mixed`>	Field to value pairs

Returns
Type	Description
`int`	The count of the documents

Throws
Type	Conditions
`Unreachable`	If the connection fails
`Unretrievable`	If the result cannot be returned
`Generic`	If any other database problem occurs

doCreate

protected function doCreate(ConstMap<string,mixed> $record)

Creates a record.

Parameters
Name	Type	Description
`$record`	`ConstMap`<`string`,`mixed`>	The record to insert, ready to go

Returns
Type	Description
`WriteResult`	Whatever MongoDB returns

Throws
Type	Conditions
`Unreachable`	If the connection fails
`Violating`	If a constraint is violated
`Generic`	If any other database problem occurs

doDelete

protected function doDelete(mixed $id)

Deletes a record.

Parameters
Name	Type	Description
`$id`	`ObjectID` \| `string`	The document identifier, either a string or `ObjectID`

Returns
Type	Description
`WriteResult`	Whatever MongoDB returns

Throws
Type	Conditions
`Unreachable`	If the connection fails
`Unretrievable`	If the document doesn't exist
`Generic`	If any other database problem occurs

doPersist

protected function doPersist(Persistable $record)

Creates a record using a MongoDB Persistable.

Since: 0.3.0

Parameters
Name	Type	Description
`$record`	`Persistable`	The document to insert, ready to go

Returns
Type	Description
`WriteResult`	Whatever MongoDB returns

Throws
Type	Conditions
`Unreachable`	If the connection fails
`Violating`	If a constraint is violated
`Generic`	If any other database problem occurs

doUpdate

protected function doUpdate(mixed $id, ConstMap<string,Map<string,mixed>> $operations, ?int $version = null)

Updates a record.

Parameters
Name	Type	Description
`$id`	`ObjectID` \| `string`	The document identifier, either a string or `ObjectID`
`$operations`	`ConstMap`<`string`,`Map`<`string`,`mixed`>>	The operations to send to MongoDB
`$version`	`?int`	Optional version for optimistic lock checking

Returns
Type	Description
`WriteResult`	Whatever MongoDB returns

Throws
Type	Conditions
`Unreachable`	If the connection fails
`Unretrievable`	If the document doesn't exist
`Conflicting`	If optimistic/pessimistic lock fails
`Violating`	If a constraint is violated
`Generic`	If any other database problem occurs

doUpdateModifiable

protected function doUpdateModifiable(Modifiable $entity, ?int $version = null)

Updates a record.

Since: 0.5.1

Parameters
Name	Type	Description
`$entity`	`Modifiable`	The entity to update
`$version`	`?int`	Optional version for optimistic lock checking

Returns
Type	Description
`?WriteResult`	Whatever MongoDB returns

Throws
Type	Conditions
`Unreachable`	If the connection fails
`Conflicting`	If optimistic/pessimistic lock fails
`Violating`	If a constraint is violated
`Generic`	If any other database problem occurs

ensure

Inherited from MongoHelper

protected function ensure<Ta>(mixed $id, ?Ta $document)

Makes sure a document isn't null.

Parameters
Name	Type	Description
`$id`	`mixed`	The document identifier, either a `\MongoDB\BSON\ObjectID` or string
`$document`	`?Ta`	The document to check

Returns
Type	Description
`Ta`	Returns `$document`

Throws
Type	Conditions
`Unretrievable`	if the document is null

findAll

public function findAll(ConstMap<string,mixed> $criteria, ?Pagination $pagination = null, ?bool $totalCount = false)

Finds several records by some arbitrary criteria.

Parameters
Name	Type	Description
`$criteria`	`ConstMap`<`string`,`mixed`>	Field to value pairs
`$pagination`	`?Pagination`	Optional pagination parameters
`$totalCount`	`?bool`	Return a `CursorSubset` that includes the total number of records. This is only done if `$pagination` is not using the defaults.

Returns
Type	Description
`Iterator`<`T`>	The objects found or null if none

Throws
Type	Conditions
`Unreachable`	If the connection fails
`Unretrievable`	If the result cannot be returned
`Generic`	If any other database problem occurs

findById

public function findById(mixed $id)

Gets a single document by ID.

Parameters
Name	Type	Description
`$id`	`mixed`	The document identifier

Returns
Type	Description
`?T`	The entity

Throws
Type	Conditions
`Unreachable`	If the connection fails
`Unretrievable`	If the result cannot be returned
`Generic`	If any other database problem occurs

findOne

public function findOne(ConstMap<string,mixed> $criteria)

Finds a single record by some arbitrary criteria.

Parameters
Name	Type	Description
`$criteria`	`ConstMap`<`string`,`mixed`>	Field to value pairs

Returns
Type	Description
`?T`	The object found or null if none

Throws
Type	Conditions
`Unreachable`	If the connection fails
`Unretrievable`	If the result cannot be returned
`Generic`	If any other database problem occurs

get

public function get(mixed $id)

Gets a single document by ID, throwing an exception if it's not found.

Parameters
Name	Type	Description
`$id`	`mixed`	The document identifier

Returns
Type	Description
`T`	The entity

Throws
Type	Conditions
`Unreachable`	If the connection fails
`Unretrievable`	If the document doesn't exist
`Generic`	If any other database problem occurs

getAll

public function getAll(ConstVector<mixed> $ids)

Gets several documents by ID.

Parameters
Name	Type	Description
`$ids`	`ConstVector`<`mixed`>	Array of identifiers

Returns
Type	Description
`Traversable`<`T`>	The results

Throws
Type	Conditions
`Unreachable`	If the connection fails
`Unretrievable`	If the result cannot be returned
`Generic`	If any other database problem occurs

getFromCache

protected function getFromCache(string $id)

Gets an entry from the cache

Parameters
Name	Type	Description
`$id`	`string`	The cache key

Returns
Type	Description
`?T`	The entity found or null

getInstanceMap

public function getInstanceMap(Traversable<T> $entities)

Gets a Map that relates identifier to instance

Parameters
Name	Type	Description
`$entities`	`Traversable`<`T`>	The entities to "zip"

Returns
Type	Description
`ImmMap`<`string`,`T`>	The instances keyed by identifier

getType

Inherited from EntityRepo

abstract public function getType()

Gets the type of entity produced, mainly for ACL reasons.

Returns
Type	Description
`string`	The entity type

isResolvable

public function isResolvable(string $ref)

Gets whether or not this class supports the reference type.

Parameters
Name	Type	Description
`$ref`	`string`	The reference type (usually a MongoDB collection name)

Returns
Type	Description
`bool`	`true` if the reference type is supported

maybeCache

protected function maybeCache(?T $entity)

Possibly add the entity to the cache.

Parameters
Name	Type	Description
`$entity`	`?T`	The entity to possibly cache

Returns
Type	Description
`?T`	The same entity that came in

maybeCacheAll

protected function maybeCacheAll(Iterator<T> $entities)

Possibly add entities to the cache.

Parameters
Name	Type	Description
`$entities`	`Iterator`<`T`>	The entities to possibly cache

Returns
Type	Description
`Traversable`<`T`>	The same entities that came in

now

Inherited from MongoHelper

protected function now()

Gets the current time.

Returns
Type	Description
`UTCDateTime`	The current time

resolve

public function resolve(DbRef $ref)

Resolves a MongoDB DbRef.

Parameters
Name	Type	Description
`$ref`	`DbRef`	The DbRef to load

Returns
Type	Description
`?T`	The loaded entity or `null` if not found

Throws
Type	Conditions
`InvalidArgumentException`	If `$ref` is of an unsupported type
`Unreachable`	If the connection fails
`Unretrievable`	If the result cannot be retrieved
`Generic`	If any other database problem occurs

resolveAll

public function resolveAll(Traversable<DbRef> $refs)

Resolves a MongoDB DbRef.

Parameters
Name	Type	Description
`$refs`	`Traversable`<`DbRef`>	The DbRefs to load

Returns
Type	Description
`Traversable`<`T`>	The loaded entities

Throws
Type	Conditions
`InvalidArgumentException`	If any `$ref`s are of an unsupported type
`Unreachable`	If the connection fails
`Unretrievable`	If the result cannot be retrieved
`Generic`	If any other database problem occurs

toDate

Inherited from MongoHelper

protected function toDate(mixed $date)

Tries to parse a date.

Parameters
Name	Type	Description
`$date`	`mixed`	The possible string date value, a string, a `\DateTimeInterface`, or a `\MongoDB\BSON\UTCDateTime`

Returns
Type	Description
`?UTCDateTime`	The MongoDB datetime or null

toId

Inherited from MongoHelper

protected function toId(mixed $id)

Transforms a literal into a MongoDB ObjectId.

Parameters
Name	Type	Description
`$id`	`mixed`	If it's an `ObjectID`, returns that, otherwise creates a new `ObjectID`.

Returns
Type	Description
`ObjectID`	The ObjectID

toIds

Inherited from MongoHelper

protected function toIds(ConstVector<mixed> $ids)

Transforms literals into MongoDB ObjectIds.

Parameters
Name	Type	Description
`$ids`	`ConstVector`<`mixed`>	Goes through each entry, converts to `ObjectID`

Returns
Type	Description
`ConstVector`<`ObjectID`>	The ObjectIDs