= SoftDelete Behavior =

The `soft_delete` behavior overrides the deletion methods of a model object to make them 'hide' the deleted rows but keep them in the database. Deleted objects still don't show up on select queries, but they can be retrieved or undeleted when necessary.

== Basic Usage ==

In the `schema.xml`, use the `<behavior>` tag to add the `soft_delete` behavior to a table:
{{{
#!xml
<table name="book">
  <column name="id" required="true" primaryKey="true" autoIncrement="true" type="INTEGER" />
  <column name="title" type="VARCHAR" required="true" primaryString="true" />
  <behavior name="soft_delete" />
</table>
}}}

Rebuild your model, insert the table creation sql again, and you're ready to go. The model now has one new column, `deleted_at`, that stores the deletion date. Select queries don't return the deleted objects:

{{{
#!php
<?php
$b = new Book();
$b->setTitle('War And Peace');
$b->save();
$b->delete();
echo $b->isDeleted(); // false
echo $b->getDeletedAt(); // 2009-10-02 18:14:23
$books = BookQuery::create()->find(); // empty collection
}}}

Behind the curtain, the behavior adds a condition to every SELECT query to return only records where the `deleted_at` column is null. That's why the deleted objects don't appear anymore upon selection.

You can turn off the query alteration globally by calling the static method `disableSoftDelete()` on the related Query object:

{{{
#!php
<?php
BookQuery::disableSoftDelete();
$books = BookQuery::create()->find();
$book = $books[0];
echo $book->getTitle(); // 'War And Peace'
}}}

Note that `find()` and other selection methods automatically re-enable the `soft_delete` filter. You can also enable it manually by calling the `enableSoftDelete()` method on Peer objects.

If you want to recover a deleted object, use the `unDelete()` method:

{{{
#!php
<?php
$book->unDelete();
$books = BookQuery::create()->find();
$book = $books[0];
echo $book->getTitle(); // 'War And Peace'
}}}

If you want to force the real deletion of an object, call the `forceDelete()` method:

{{{
#!php
<?php
$book->forceDelete();
echo $book->isDeleted(); // true
$books = BookQuery::create()->find(); // empty collection
}}}

The query methods `delete()` and `deleteAll()` also perform a soft deletion, unless you disable the behavior on the peer class:

{{{
#!php
<?php
$b = new Book();
$b->setTitle('War And Peace');
$b->save();

BookQuery::create()->delete($b);
$books = BookQuery::create()->find(); // empty collection
// the rows look deleted, but they are still there
BookQuery::disableSoftDelete();
$books = BookQuery::create()->find();
$book = $books[0];
echo $book->getTitle(); // 'War And Peace'

// To perform a true deletion, disable the softDelete feature
BookQuery::disableSoftDelete();
BookQuery::create()->delete();
// Alternatively, use forceDelete()
BookQuery::create()->forceDelete();
}}}

== Parameters ==

You can change the name of the column added by the behavior by setting the `deleted_column` parameter:

{{{
#!xml
<table name="book">
  <column name="id" required="true" primaryKey="true" autoIncrement="true" type="INTEGER" />
  <column name="title" type="VARCHAR" required="true" primaryString="true" />
  <column name="my_deletion_date" type="TIMESTAMP" />
  <behavior name="soft_delete">
    <parameter name="deleted_column" value="my_deletion_date" />
  </behavior>
</table>
}}}

{{{
#!php
<?php
$b = new Book();
$b->setTitle('War And Peace');
$b->save();
$b->delete();
echo $b->getMyDeletionDate(); // 2009-10-02 18:14:23
$books = BookQuery::create()->find(); // empty collection
}}}