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: the mondoc_retention connection

The MondocRetentionService uses the connection ID mondoc_retention, which you must register with MondocConfig. Without it, the first save of a model using the trait throws a MondocConfigConfigurationException. See Step 1 of the example below.

When using the MondocRetentionTrait trait, you can set the retention data for a model by calling setMondocRetentionChangeMeta. 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 setMondocRetentionExpiry method is exposed, and can be used to set the expiry date for the retained data. Pass null for 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 null expiry, 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 MondocRetentionService to query for data that has expired, using either getPaginatorForExpiredRetentionForClassName or getPaginatorForExpiredRetentionForObject, and then subsequently the getRetentionPage method.

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. null means 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 MondocRetentionModel objects. A shortcut to MondocRetentionService::getRetentionPage.

Any MondocAbstractModel also exposes isMondocRetentionEnabled(): bool, which returns true when the model uses the MondocRetentionTrait.

Watch the argument order

The pagination helper methods do not share the same argument order. getRetentionHistoryPaginationHelperForClassName, getRetentionHistoryPaginationHelperForModel and the trait's getRetentionPaginatorForModel take ($perPage, $currentPage), whereas getPaginatorForExpiredRetentionForClassName and getPaginatorForExpiredRetentionForObject take ($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 MondocRetentionTrait trait.

  • 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 addIndexes to 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 getPaginatorForExpiredRetentionForClassName or getPaginatorForExpiredRetentionForObject.

Exposed methods in MondocRetentionModel

  • setSourceModel(MondocAbstractModel $model): void
    Note:
    You don't need to call this if you're using the create method on the MondocRetentionService.

    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 via setMondocRetentionChangeMeta. 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 the MondocRetentionTrait.

  • 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 setSourceModelData method, 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 the MondocRetentionTrait. This can be returned as a DateTime object, or as a UTCDateTime object if $asMongo is set to true.

  • 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 true if the retention data has expired, and false if 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);