README

Adds "soft"-delete support to CakePHP 3 tables.

Install

composer require queencitycodefactory/trash

You then need to load the plugin. You can use the shell command:

bin/cake plugin load QueenCityCodeFactory/Trash

or by manually adding statement shown below to Application.php:

$this->addPlugin('QueenCityCodeFactory/Trash');

Usage

In your table(s), add the behavior like you would for any other behavior:

// in the initialize() method
$this->addBehavior('QueenCityCodeFactory/Trash.Trash');

By default, the behavior will auto-detect the DATETIME column used to track trashed (soft-deleted) records but only if you are using deleted or trashed as names. Otherwise, you could customize that when adding the behavior:

// in the initialize() method
$this->addBehavior('QueenCityCodeFactory/Trash.Trash', [
    'field' => 'deleted_at'
]);

or, at the global level, in bootstrap.php:

Configure::write('QueenCityCodeFactory/Trash.field', 'deleted_at');

Finally, if you would like to keep the default cake behavior when running find() or delete() operations and explicitly call the behavior when you need 'trash'-ing functionality, just disable the event(s):

// in the initialize() method
$this->addBehavior('QueenCityCodeFactory/Trash.Trash', [
    'events' => ['Model.beforeFind'] // enables the beforeFind event only, false to disable both
]);

Cascading deletion

If you'd like to have related records marked as trashed when deleting a parent item, you can just attach the behavior to the related table classes, and set the 'dependent' => true, 'cascadeCallbacks' => true options in the table relationships.

This works on relationships where the item being deleted in the owning side of the relationship. Which means that the related table should contain the foreign key.

Custom Finders

onlyTrashed - helps getting only those trashed records.
withTrashed - when filtering out the trashed records by default, this method comes in handy to have them included as part of certain calls.

Extras

emptyTrash() - permanently deletes all trashed records.
restoreTrash($entity = null) - restores one (or all) trashed records.
trash($entity) - like delete() but for a soft-delete (handy when Model.beforeDelete is disabled by default).
trashAll(array $conditions) - like deleteAll() but for soft-deletes.

Patches & Features

Fork
Mod, fix
Test - this is important, so it's not unintentionally broken
Commit - do not mess with license, todo, version, etc. (if you do change any, bump them into commits of their own that I can ignore when I pull)
Pull request - bonus point for topic branches

To ensure your PRs are considered for upstream, you MUST follow the CakePHP coding standards.

Bugs & Feedback

http://github.com/QueenCityCodeFactory/trash/issues

queencitycodefactory / trash

Maintainers

Details