= 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 = BookPeer::doSelect(new Criteria()); // empty array
}}}

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 Peer object:

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

Note that `doSelect()` 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 = BookPeer::doSelect(new Criteria());
$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 = BookPeer::doSelect(new Criteria()); // empty array
}}}

The static Peer methods `doDelete()` and `doDeleteAll()` 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();

BookPeer::doDelete($b);
$books = BookPeer::doSelect(new Criteria()); // empty array
// the rows look deleted, but they are still there
BookPeer::disableSoftDelete();
$books = BookPeer::doSelect(new Criteria());
$book = $books[0];
echo $book->getTitle(); // 'War And Peace'

// To perform a true deletion, disable the softDelete feature
BookPeer::disableSoftDelete();
BookPeer::doDeleteAll();
// Alternatively, use doForceDelete()
BookPeer::doForceDeleteAll();
}}}

== Parameters ==

By default, the behavior adds one column to the model. If this column is already described in the schema, set the `add_columns` parameter to 'false', as follows:

{{{
#!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="deleted_at" type="TIMESTAMP" />
  <behavior name="soft_delete">
    <parameter name="add_columns" value="false" />
  </behavior>
</table>
}}}

You can also change the name of the column 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="add_columns" value="false" />
    <parameter name="deleted_column" value="my_deletion_date" />
  </behavior>
</table>
}}}

If you keep the `add_columns` parameter to 'true' by set custom column name, then the behavior will generate this column:

{{{
#!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">
    <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 = BookPeer::doSelect(new Criteria()); // empty array
}}}
