About \District5\Mondoc\Db\Model\Traits\MondocRetentionTrait

Full namespace: \District5\Mondoc\Db\Model\Traits\MondocRetentionTrait

The MondocRetentionTrait trait is useful for ensuring that data is retained for a certain period of time. This is useful for compliance with data retention policies, and can be used to ensure that data is not deleted before a certain period of time has passed.

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. The library does not automatically delete the data when the retention period has expired.

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 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

  Set the change meta for the retention model. This is useful for setting things such as the user's name who initiated the change, or similar for compliance and the retention policy.

• 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 enforce data retention on your models.

Step 1: Add the trait to your model

The trait tells Mondoc that this model should have data retention enforced upon on 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 setName(string $name): void
    {
        $this->name = $name;
    }
}

Step 2: 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 3: 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 4: Querying the data

The retention history data will be controlled via the description MondocRetentionService

<?php
// Getting a pagination helper
$paginator = \District5\Mondoc\Extensions\Retention\MondocRetentionService::getRetentionHistoryPaginationHelperForClassName(
    MyModel::class,
    10,
    10,
    ['user' => 'joe.bloggs']
);

// Fetching a page of results
$results = \District5\Mondoc\Extensions\Retention\MondocRetentionService::getPage(
    $paginator // The filter is carried through by the pagination helper
);

//
// The results will be an array of `MondocRetentionModel`'s
//
echo count($results); // 2

//
// 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

Recommended reading:

• description Model » learn how to define your models
• description Model traits » learn how to use traits to enhance your model

Documentation homefast_rewind Query buildingfast_forward