Download the PHP package spatie/laravel-deleted-models without Composer

Automatically copy deleted records to a separate table

When deleting an Eloquent model, this package will copy the attributes of that model to a new table called deleted_models. You can view this as a sort of "Recycle bin for models".

To restore a previous model you can call restore and pass the id.

This way of preserving information when deleting can be seen as an alternative to soft deletes. You can read more on the trade-offs in this blog post.

Support us

We invest a lot of resources into creating best in class open source packages. You can support us by buying one of our paid products.

We highly appreciate you sending us a postcard from your hometown, mentioning which of our package(s) you are using. You'll find our address on our contact page. We publish all received postcards on our virtual postcard wall.

Installation

You can install the package via composer:

To create the deleted_models table, you can publish and run the migrations with:

Optionally, you can publish the config file with:

This is the contents of the published config file:

The pruning of the deleted_models table depends on Laravel's native pruning feature. Don't forget to schedule the model:prune as instructed in Laravel's docs.

Usage

You should add the KeepsDeletedModels trait to all models whose attributes should be written to deleted_models whenever the model is deleted.

With this in place, the attributes will be written to deleted_models when the model is deleted.

To restore a previous model you can call restore and pass the id.

If the model to be restored can't be found in the deleted_models table, a Spatie\DeletedModels\Exceptions\NoModelFoundToRestore exception will be thrown.

Restoring without saving

To restore in memory, without actually saving it, you can call makeRestored. Keep in mind that calling this method will also remove the record in the deleted_models_table.

If the model to be restored can't be found in the deleted_models table, null will be returned by makeRestored.

Restoring without emitting events

By default, the Spatie\DeletedModels\Events\RestoringDeletedModelEvent and Spatie\DeletedModels\Events\DeletedModelEvent will be dispatched when calling restore on a model.

If you don't want these events to be dispatched, call restoreQuietly.

Customizing the restore process

Using closures passed to restore

The restore function accepts a callable as the second argument. The beforeSaving callable will be executed when the restored model was created in memory, but before saving it in the db.

Using methods on the model

If you need to run some logic to before and after restoring a model, you can implement beforeRestoringModel and afterRestoringModel on your model.

To determine which attributes and values should be kept in deleted_models, you can implement attributesToKeep

Pruning deleted models

After a while, the deleted_models table can become large. The DeletedModel implements Laravel's native MassPrunable trait.

You can configure the number of days records in the deleted_models will be pruned in the prune_after_days key of the deleted-models.php config file. By default, all deleted models will be kept for 365 days.

Don't forget to schedule the model:prune as instructed in Laravel's docs.

Low-level customization of the delete and restoration process

The DeletedModel model implements most logic to keep and restore deleted models. You can modify any of the behaviour by creating a class that extends Spatie\DeletedModels\Models\DeletedModel. You should put the class name of your extended class in the model key of the deleted-models.php config file.

With this in place you can override any of the methods in DeletedModel.

Testing

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Freek Van der Herten
• All Contributors

This package was inspired by these two blog posts:

• Easy, alternative soft deletion
• [this one](Soft Deletion Probably Isn't Worth It).

License

The MIT License (MIT). Please see License File for more information.