Model » Lifecycle hooks
Run custom logic — or veto an operation entirely — at key points in a model's lifecycle.
About lifecycle hooks
MondocAbstractModel exposes six hook methods that fire around the
three mutating operations: insert, update, and delete. Each pair consists of a before* hook
that can cancel the operation by returning false, and an after* hook that runs
once the operation has completed successfully.
All six hooks have default no-op implementations in MondocAbstractModel, so you only need to override the ones you care about.
Hook methods
-
beforeInsert(): bool
Called before this model is inserted. Return
falseto cancel the insert; the service method will returnfalsewithout persisting the document. -
afterInsert(): void
Called after this model has been successfully inserted. The model will already have its
ObjectIdassigned at this point. -
beforeUpdate(): bool
Called before this model is updated. Return
falseto cancel the update; the service method will returnfalsewithout persisting any changes. -
afterUpdate(): void
Called after this model has been successfully updated.
-
beforeDelete(): bool
Called before this model is deleted. Return
falseto cancel the deletion; the service method will returnfalsewithout removing the document. -
afterDelete(): void
Called after this model has been successfully deleted. The model's
ObjectIdwill have been unset at this point.
Example
The example below shows a model that uses hooks to validate data before insertion, stamp an audit log after updates, and prevent active records from being deleted.
<?php
use District5\Mondoc\Db\Model\MondocAbstractModel;
class MyModel extends MondocAbstractModel
{
protected string $name = '';
protected bool $active = true;
public function getName(): string
{
return $this->name;
}
public function setName(string $name): void
{
$this->name = $name;
}
public function setActive(bool $active): void
{
$this->active = $active;
}
// Prevent inserting a model with an empty name
public function beforeInsert(): bool
{
return $this->name !== '';
}
// Run custom logic after every successful update
public function afterUpdate(): void
{
// e.g. log the change, dispatch an event, notify a subscriber...
}
// Prevent deleting active records
public function beforeDelete(): bool
{
return !$this->active;
}
}
// Assumes MyModel is mapped to MyService in MondocConfig (addServiceMapping)
$model = new MyModel();
$model->setName(''); // empty name
$model->save(); // returns false — beforeInsert vetoed the insert
$model->setName('Alice');
$model->save(); // returns true — inserted successfully
Hooks and insertMulti()
Hooks fire per-model when using
insertMulti(). Any model whose
beforeInsert() returns false is silently skipped; the remaining models
are inserted as a single batch. afterInsert() is called on each model that was
successfully inserted. If every model is vetoed, nothing is inserted and
insertMulti() returns false.
<?php
$alice = new MyModel();
$alice->setName('Alice');
$noName = new MyModel();
// setName not called — beforeInsert() will veto this one
MyService::insertMulti([$alice, $noName]);
// $alice is inserted: $alice->hasObjectId() === true
// $noName is skipped: $noName->hasObjectId() === false
Which methods fire hooks?
Hooks are only called when Mondoc is working with a model instance. Methods which operate directly on a filter or on IDs do not load the models, and so cannot call their hooks.
| Fires hooks | Does not fire hooks |
|---|---|
$model->save() / MyService::saveModel()MyService::insert()MyService::insertMulti()MyService::update()MyService::updateManyModels()$model->delete() / MyService::deleteModel()
|
MyService::deleteModels()MyService::delete($id), deleteOne(), deleteMulti(), deleteByIds()MyService::updateOne(), updateMany(), updateManyByQueryBuilder()Atomic and array operators (e.g. inc(), dec(), push/pull helpers)
|
Please note:
beforeUpdate()is not called if the model has no dirty (changed) fields. In that case update() returnstruestraight away, without writing anything, andafterUpdate()is not called either.- When saving, Mondoc sets the trait-managed values before the
before*hook runs: the created date (cd), modified date (md) and revision number (_rn) on insert (including insertMulti()), and the modified date and revision number on update. If your hook vetoes the operation, those in-memory values have still been changed on the model.