Doctrine SoftDelete behavior usage

Scene from "The Neverending Story" by Wolfgang Petersen (1984)

SoftDelete

Recently, I created a detailed list of Doctrine behaviors ready to use in symfony projects. Among them, there is the SoftDelete behavior I want to focus on this time. For a chosen model, it adds a deleted_at column, which defines if a record has been marked as deleted (and if so, when).

where to use it?

Suppose your system needs to store all the detailed data history, every modification has to be marked and stay there forever. And even if the application allows users to delete objects, they are not really deleted - it is just an abstraction layer - in fact, objects are marked as deleted, but they stay in the database (and the application treats them as if they were deleted). This is where SoftDelete comes handy.

the code

All you gotta do is just to state that a given model is SoftDelete:

GivenModel:
  actAs:
    SoftDelete: ~

After this, the deleted_at column is added (of course, both to SQL and PHP class). But that's not all the job. Unfortunately, you have to tell the application how to use this column manually. Fortunately, this is really easy. For example, if you have an admin generated module, soft-deleted objects shall never appear in the list. Add/modify the buildQuery action of the admin module:

protected function buildQuery()
  {
    return parent::buildQuery()
      ->andWhere('deleted_at IS NULL');
  }

Additionally, if you want to have a full protection, you should update your admin module edit action to disable executing it for a soft-deleted object. So this was for the backend. For frontend, you shall modify your eventual data retrieving table class methods, like the following:

public function getObjectByIdQuery($id)
  {
    return Doctrine_Query::create()
      ->from('GivenModel gm')
      ->where('gm.id = ?', $id)
      ->andWhere('gm.deleted_at IS NULL');
  }

Of course, soft-deleted objects can NEVER be accessible from any type of frontend applications. There is no way to give a detailed list of modifications you need to provide 100% data protection, because all applications have different structure - you have to go through your functionalities on your own. These code lines above are just examples you will probably use.

enable DQL callbacks

Alternatively, you may enable DQL callbacks for your models in each of your config/ProjectConfiguration.class.php files:

public function configureDoctrine(Doctrine_Manager $manager)
  {
    // Enable callbacks so that softDelete behavior can be used
    $manager->setAttribute(Doctrine_Core::ATTR_USE_DQL_CALLBACKS, true);
  }

this will dynamically add an andWhere DQL clause to all SELECT queries for SoftDelete models (Doctrine_Template_Listener_SoftDelete::preDqlDelete()). Thanks to it, you don't have to manually update all possible SELECT queries in your project (such as buildQuery mentioned above).

be careful!

As the official behavior docs say, SoftDelete overrides the delete() method. When delete() is called, instead of deleting the record from the database, a deleted_at date is set. This means, if you try to delete records without using Doctrine_Record::delete() method, SoftDelete won't work! To provide 100% data protection covering SoftDelete you should replace all code like

Doctrine_Query::create()
  ->delete()
  ->from('GivenModel gm')
  ->where('gm.id = ?', $id)
  ->execute();

with

$objects = Doctrine_Query::create()
  ->from('Manufacturer m')
  ->where('m.id = ?', $id)
  ->execute();
 
foreach($objects as $object)
  $object->delete();

to make the Doctrine_Record::delete() be called whenever an object is supposed to be deleted, which finally means that the desired SoftDelete behavior is fired always when it should be.

objects related to SoftDelete-able objects

But there comes another question - what to do with related records of a soft-deleted object? For example, we have two model classes with the SoftDelete behavior: Manufacturer and Supplier which have a m:n relation table, ManufacturerSupplier which defines who supplies which manufacturers. If some specific manufacturer and supplier objects are marked as soft-deleted, their corresponding ManufacturerSupplier object (if it exists, let's suppose it does) is left and no one knows how to treat it. It is not marked as soft-deleted, since it hasn't got SoftDelete behavior. And it still exists in the database, like a full-fledged record. Probably, it does not raise any application problems, but there is a data consistency question - what does such m:n table record represent, when at least one of its related objects are soft-deleted? Shall it be soft-deleted after the related master object is soft-deleted? Or maybe hard-deleted?