Model » Data retention with Mondoc
Mondoc provides a way to enforce data retention policies on your models. This feature is useful when you need to ensure that all data is retained for at least a certain period of time.
About \District5\Mondoc\Db\Model\Traits\MondocRetentionTrait
Full namespace: \District5\Mondoc\Db\Model\Traits\MondocRetentionTrait
The MondocRetentionTrait trait gives your model a change history with optional expiry.
Each time a model using the trait is inserted (via insert, insertMulti or
save) or updated (via update, updateManyModels or
save), a snapshot of the model is stored in a separate mondoc_retention
collection. This is useful for auditing and for compliance with data retention policies.
Mondoc does not prevent the original model from being deleted, and deleting a model does not create a snapshot. An update where nothing has changed (no dirty fields) also does not create a snapshot.
Required setup: themondoc_retentionconnectionThe
MondocRetentionServiceuses the connection IDmondoc_retention, which you must register withMondocConfig. Without it, the first save of a model using the trait throws aMondocConfigConfigurationException. See Step 1 of the example below.
When using the
MondocRetentionTraittrait, you can set the retention data for a model by callingsetMondocRetentionChangeMeta. There is no preset retention data, so you must set this yourself. This is useful for setting things such as the user's name who initiated the change, or similar for compliance and the retention policy.Additionally, the method
setMondocRetentionExpirymethod is exposed, and can be used to set the expiry date for the retained data. Passnullfor data which never expires. The library does not automatically delete the data when the retention period has expired.The change meta and expiry are not stored on the model's own document. A model retrieved from the database starts with empty change meta and a
nullexpiry, and the values on an in-memory model are reused for every subsequent save until you change them. Set both again before each save.You can use the
MondocRetentionServiceto query for data that has expired, using eithergetPaginatorForExpiredRetentionForClassNameorgetPaginatorForExpiredRetentionForObject, and then subsequently thegetRetentionPagemethod.
Exposed methods in MondocRetentionTrait
-
setMondocRetentionChangeMeta(array $data): static
Set arbitrary metadata to store alongside the next snapshot, for example who made the change.
-
getMondocRetentionChangeMeta(): array
-
setMondocRetentionExpiry(DateTime|UTCDateTime|null $expiry): static
Set the expiry date for the next snapshot.
nullmeans the snapshot never expires. -
getMondocRetentionExpiry(): DateTime|UTCDateTime|null
-
getRetentionPaginatorForModel(int $perPage, int $currentPage): MondocPaginationHelper
Get a pagination helper for this model's history. If the model has not been saved yet, this returns a helper covering every snapshot of the model's class.
-
getRetentionPageByPaginator(MondocPaginationHelper $paginator, string $sortByField = '_id', int $sortDirection = -1): MondocRetentionModel[]
Get a page of
MondocRetentionModelobjects. A shortcut toMondocRetentionService::getRetentionPage.
Any MondocAbstractModel also exposes isMondocRetentionEnabled(): bool, which
returns true when the model uses the MondocRetentionTrait.
Watch the argument orderThe pagination helper methods do not share the same argument order.
getRetentionHistoryPaginationHelperForClassName,getRetentionHistoryPaginationHelperForModeland the trait'sgetRetentionPaginatorForModeltake($perPage, $currentPage), whereasgetPaginatorForExpiredRetentionForClassNameandgetPaginatorForExpiredRetentionForObjecttake($currentPage, $perPage). Using named arguments (e.g.perPage: 10, currentPage: 1) avoids mistakes.
Exposed methods in MondocRetentionService
-
create(MondocAbstractModel $model): void
Create a new retention model. This is called automatically by Mondoc when a model contains the
MondocRetentionTraittrait. -
createStub(MondocAbstractModel $model): MondocRetentionModel
Create a new retention model, but don't save it. This is useful for creating a retention model that you want to save at a later date. This is used when inserting multiple models.
-
getLatestRetentionModelForModel(string $class, ObjectId $objectId): ?MondocRetentionModel
Get the latest retention model for a given (previously saved) model.
-
countRetentionModelsForClassName(string $class): int
Count the number of retention models for a given class name.
-
countRetentionModelsForModel(MondocAbstractModel $object): int
Count the number of retention models for a given (previously saved) model.
-
getRetentionHistoryPaginationHelperForClassName(string|MondocAbstractModel $class, int $perPage, int $currentPage): MondocPaginationHelper
Get a pagination helper for the retention history for a given class name.
-
getRetentionHistoryPaginationHelperForModel(MondocAbstractModel $source, int $perPage, int $currentPage): MondocPaginationHelper
Get a pagination helper for the retention history for a given (previously saved) model.
-
addIndexes(): void
Add the indexes to the retention collection. This is NOT called automatically by Mondoc, and must be called manually by your application.
-
hasIndexes(): bool
Check if the indexes have been added to the retention collection. This is a helper method to allow you to check if the indexes have been added, and if not, you can call
addIndexesto add them. -
getPaginatorForExpiredRetentionForClassName(string|MondocAbstractModel $className, int $currentPage, int $perPage): MondocPaginationHelper
Get a pagination helper for the retention history for a given class name, where the retention has expired.
-
getPaginatorForExpiredRetentionForObject(MondocAbstractModel $object, int $currentPage, int $perPage): MondocPaginationHelper
Get a pagination helper for the retention history for a given (previously saved) model, where the retention has expired.
-
getRetentionPage(MondocPaginationHelper $paginator, string $sortByField = '_id', int $sortDirection = -1): array
Get a page of retention models from the pagination helper. This is the method you use after retrieving a pagination helper via
getPaginatorForExpiredRetentionForClassNameorgetPaginatorForExpiredRetentionForObject.
Exposed methods in MondocRetentionModel
-
setSourceModel(MondocAbstractModel $model): void
Note:
You don't need to call this if you're using thecreatemethod on theMondocRetentionService.Set the source model for the retention model. This automatically calls the following methods:
-
setSourceModelData -
setSourceObjectId -
setSourceClassName -
setRetentionData -
setRetentionExpiry -
setCreatedDate
-
-
toOriginalModel(): MondocAbstractModel
Rebuild an instance of the original model (e.g.
MyModel) from the stored snapshot, with its change meta re-applied viasetMondocRetentionChangeMeta. The inflated model is cached on the retention model, so repeated calls return the same instance. -
getSourceModelData(): array
Get the data that was saved at the time of the retention data being saved. This will return the data as it was saved at the time of the retention data being saved, in array format.
-
setSourceModelData(array|BSONDocument $data): static
Set the data that was saved at the time of the retention data being saved.
-
getSourceObjectId(): ObjectId
Get the ObjectId of the original model that the retention data is associated with.
-
getSourceObjectIdString(): string
Get the ObjectId of the original model that the retention data is associated with, as a string.
-
setSourceObjectId(ObjectId $srcId): static
Set the ObjectId of the original model.
-
getSourceClassName(): string
Get the class name of the original model that the retention data is associated with.
-
setSourceClassName(string $class): static
Set the class name of the original model.
-
getRetentionData(): array
Get the retention data that was saved at the time of the retention data being saved, as set by the original call to
setMondocRetentionChangeMeta, contained in theMondocRetentionTrait. -
setRetentionData(array $retention): static
Set the retention data for the model, for example the user's name who initiated the change, or similar. This is different from the
setSourceModelDatamethod, which sets the data that was saved at the time of the retention data being saved. -
getRetentionExpiry(bool $asMongo = false): DateTime|UTCDateTime|null
Get the retention expiry date that was saved at the time of the retention data being saved, as set by the original call to
setMondocRetentionExpiry, contained in theMondocRetentionTrait. This can be returned as aDateTimeobject, or as aUTCDateTimeobject if$asMongois set totrue. -
setRetentionExpiry(DateTime|UTCDateTime|null $expiry): static
Set the retention expiry date for the model. This is the date that the retention data will expire.
-
hasRetentionExpired(): bool
Check if this retention model has expired. This will return
trueif the retention data has expired, andfalseif it has not.
A working example of data retention
Next, we'll show you a simple example of how to use the MondocRetentionTrait trait to
keep a change history of your models.
Step 1: Register the mondoc_retention connection
The MondocRetentionService uses the connection ID mondoc_retention. You must
register a database under this ID, alongside your normal configuration.
<?php
$client = new \MongoDB\Client('mongodb://localhost:27017');
$config = \District5\Mondoc\MondocConfig::getInstance();
// your normal connection
$config->addDatabase(
$client->selectDatabase('my_database')
);
// required for data retention. This can be the same database, or a different one.
// The snapshots are stored in the 'mondoc_retention' collection.
$config->addDatabase(
$client->selectDatabase('my_database'),
'mondoc_retention'
);
// map your model to your service, as normal
$config->addServiceMapping(
MyModel::class,
MyService::class
);
// optional, but recommended: add the retention indexes once (e.g. during deployment)
if (\District5\Mondoc\Extensions\Retention\MondocRetentionService::hasIndexes() === false) {
\District5\Mondoc\Extensions\Retention\MondocRetentionService::addIndexes();
}
Step 2: Add the trait to your model
The trait tells Mondoc that this model should have a change history kept for it. The trait exposes the necessary methods to assign data, such as expiration date, or information about the change, for example the user who initiated the change, or similar.
<?php
class MyModel extends \District5\Mondoc\Db\Model\MondocAbstractModel
{
use \District5\Mondoc\Db\Model\Traits\MondocRetentionTrait;
protected string|null $name = null;
public function getName(): string|null
{
return $this->name;
}
public function setName(string $name): void
{
$this->name = $name;
}
}
Step 3: Create a service for your model
There is no change to your normal service class. Your data model will still run from your service.
<?php
class MyService extends \District5\Mondoc\Db\Service\MondocAbstractService
{
protected static function getCollectionName(): string
{
return 'data';
}
}
Step 4: Create some data
<?php
$model = new MyModel();
$model->setName('John Doe');
$model->setMondocRetentionChangeMeta([
'user' => 'joe.bloggs',
]);
$model->setMondocRetentionExpiry(
(new DateTime())->modify('+30 days')
); // this data will expire in 30 days
$model->save();
// for the sake of the example, we'll retrieve the model and update it
$retrieved = MyService::getById($model->getObjectId());
$retrieved->setName('Jane Doe');
$retrieved->setMondocRetentionChangeMeta([
'user' => 'jane.bloggs',
]);
$retrieved->setMondocRetentionExpiry(
null
); // this data will never expire
$retrieved->save();
Step 5: Querying the data
The retention history data will be controlled via the description MondocRetentionService
<?php
use District5\Mondoc\Extensions\Retention\MondocRetentionService;
// Getting a pagination helper for the full history of MyModel.
// Note: the argument order here is ($class, $perPage, $currentPage)
$paginator = MondocRetentionService::getRetentionHistoryPaginationHelperForClassName(
MyModel::class,
10, // per page
1 // current page
);
// or, for a single saved model:
// $paginator = MondocRetentionService::getRetentionHistoryPaginationHelperForModel($model, 10, 1);
// Fetching a page of results (newest first, by default)
$results = MondocRetentionService::getRetentionPage(
$paginator
);
//
// The results will be an array of `MondocRetentionModel`'s
//
echo count($results); // 2
echo $results[0]->getRetentionData()['user']; // jane.bloggs
echo $results[1]->getRetentionData()['user']; // joe.bloggs
//
// We can easily inflate the original `MyModel` from a result
//
$firstResult = $results[0]->toOriginalModel();
echo $firstResult->getName(); // Jane Doe
$secondResult = $results[1]->toOriginalModel();
echo $secondResult->getName(); // John Doe
//
// Finding snapshots whose expiry date has passed.
// Note: the argument order here is ($className, $currentPage, $perPage)
//
$expiredPaginator = MondocRetentionService::getPaginatorForExpiredRetentionForClassName(
MyModel::class,
1, // current page
10 // per page
);
$expired = MondocRetentionService::getRetentionPage($expiredPaginator);