README

Purpose

This CakePHP plugin enables you to make your models soft deletable. When soft deleting an entity, it is not actually removed from your database. Instead, a deleted timestamp is set on the record.

Requirements

CakePHP 3.5.0 or later

Installation

You can install this plugin into your CakePHP application using composer.

Update your composer file to include this plugin:

composer require funayaki/cakephp3-soft-delete

Configuration

Load the plugin:

// In /config/bootstrap.php
Plugin::load('SoftDelete');

Make a model soft deleteable:

Use the SoftDeleteTrait and implement the SoftDeleteAwareInterface on your model Table class:

// in src/Model/Table/UsersTable.php
...
use SoftDelete\Model\Table\Entity\SoftDeleteAwareInterface;
use SoftDelete\Model\Table\SoftDeleteTrait;

class UsersTable extends Table implements SoftDeleteAwareInterface
{
    use SoftDeleteTrait;

    public function getSoftDeleteField()
    {
        return 'deleted';
    }

    public function getSoftDeleteValue()
    {
        return date('Y-m-d H:i:s');
    }

    public function getRestoreValue()
    {
        return null;
    }
}

Use

Soft deleting records

delete and deleteAll functions will now soft delete records by populating deleted field with the date of the deletion.

// in src/Model/Table/UsersTable.php
$this->delete($user); // $user entity is now soft deleted if UsersTable uses SoftDeleteTrait.

Restoring Soft deleted records

To restore a soft deleted entity into an active state, use the restore method:

// in src/Model/Table/UsersTable.php
// Let's suppose $user #1 is soft deleted.
$user = $this->Users->find('all', ['withDeleted'])->where('id', 1)->first();
$this->restore($user); // $user #1 is now restored.

Finding records

find, get or dynamic finders (such as findById) will only return non soft deleted records. To also return soft deleted records, $options must contain 'withDeleted'. Example:

// in src/Model/Table/UsersTable.php
$nonSoftDeletedRecords = $this->find('all');
$allRecords            = $this->find('all', ['withDeleted']);

Hard deleting records

To hard delete a single entity:

// in src/Model/Table/UsersTable.php
$user = $this->get($userId);
$success = $this->hardDelete($user);

To mass hard delete records that were soft deleted before a given date, you can use hardDeleteAll($date):

// in src/Model/Table/UsersTable.php
$date = new \DateTime('some date');
$affectedRowsCount = $this->hardDeleteAll([
    $this->getSoftDeleteField() . ' <=' => $date->format('Y-m-d H:i:s')
]);

Soft deleting & associations

Associations are correctly handled by SoftDelete plugin.

Soft deletion will be cascaded to related models as usual. If related models also use SoftDelete Trait, they will be soft deleted.
Soft deletes records will be excluded from counter caches.

funayaki / cakephp3-soft-delete

Maintainers

Details