The soft side of the delete button

jake’s headshot By Jake, 13 Apr 2020

We've all been there. You get a call that someone deleted content from their website, they don't know how to get it back and they're (understandably) upset. Before the 3.1 release of Craft CMS you might have been in a pinch. You could restore an old copy of the database, assuming you have backups, but then you risk overwriting newer content. It's not an impossible problem to fix, but you'd definitely be in for a bummer of an afternoon.

This is why the Craft team introduced Soft Deletes. Now, when you delete an entry, category, user or any type of element, it is automatically placed in a "Trashed" state, where it is recoverable, but won't appear in the dashboard or in any templates.

In this article, we'll be diving into the following topics:

  • What types of content have a soft-delete
  • How to soft-delete content
  • How to find and recover soft-deleted content
  • How to permanently remove soft-deleted content
  • Configuring soft-delete
  • What this means for plugin authors

What types of content will be soft-deleted?

Great question! The short answer: anything that is an "element" in Craft. The main types of content that you'll be working with soft-deletes in Craft are:

  • Entries
  • Categories
  • Users
  • Assets*

Other entities in Craft like sections, entry types and category groups are also soft-delete-enabled, but you can't restore them from the Control Panel (CP), and probably won't bump into many scenarios where you'd want to recover those elements manually, especially if you're using Project Config.

*Assets cannot be recovered from the CP, which we'll discuss below

How to soft delete content

Soft delete is automatically enabled if you're using Craft CMS 3.1+, so you can delete your content normally and it will automatically be soft-deleted.

Deleting an entry from the Craft CMS control panel

How to find and recover soft-deleted content

Here's the fun part! The whole reason to have soft-delete is so that you can find and recover content that was mistakenly deleted.

Finding soft-deleted content

When you delete an entry (or another element) it's marked as "Trashed" and will no longer show up in the normal list of entries in the Control Panel.

To find and manage soft-deleted entries, you can click on the "status" indicator (to the right of the search bar) and select a new status option called "Trashed." This works for Entries, Categories, Users and Assets.

Looking in the Trash in the Craft CMS control panel

Within this view, you can see all of the content that has been soft-deleted, but has not yet been permanently removed (see the next section for how/when content is permanently removed).

The Trash in the Craft CMS control panel

As you can see, the Deleted Blog Post entry showing up under Trashed still has a status of "enabled" even though it has been deleted. Don't worry about this, it won't show up on the front end or in any searches.

Recovering soft-deleted content

To recover an item that's been soft-deleted, find the trashed element and select it. Once you've selected it, the filtering bar at the top will disappear and a "Restore" button will appear. Click "restore" to restore all selected entries.

Recovering soft-deleted content in Craft CMS

Note: Entries, Users and Categories can all be restored from the Control Panel, but Assets cannot. This is because when you delete an asset, the file related to that asset is automatically removed from the server (either your server or a remote). This makes it difficult to "restore" an asset.

How to permanently remove soft-deleted content

From the control panel

Do you want the good news or the bad news first? The bad news? Okay. Currently, there's no way to permanently delete soft-deleted content from the CMS. But, the good news is that it's coming in Craft 3.5.

Once Craft 3.5 is released, you'll be able to permanently delete content that's been soft-deleted by navigating to the Trashed screen and clicking "Delete Permanently."

Deleting items in the Trash in Craft CMS 3.5

With a console command

You can, however, remove soft-deleted content using a Console Command that's built into Craft. I won't go into exactly how this works, but just know that soft-deleted entries are eventually garbage-collected automatically*, but you can run this command to remove them early.

// remove all soft-deleted elements immediately (Entries, Users, etc.)
./craft gc --delete-all-trashed

*Unless you tell Craft never to remove soft-deleted content (see Configuration section below)

Configuring soft-delete

By default, soft-deleted content is kept for 30 days, and then will be automatically removed. But you can configure this to keep content for a shorter period, a longer period or forever.

Using the softDeleteDuration config:

// general.php

return [
'softDeleteDuration' => 0 // zero means that trashed content will be kept forever
]

What this means for plugin authors

Soft Delete doesn't just work for native Craft element types, any custom element that a plugin adds can also leverage the Soft Delete functionality.

Examples

Inventory

Lindsey DiLoreto recently updated his plugin Inventory, which helps you keep an inventory of where your fields are being used and track if fields were being used in a now-deleted section.

Craft CMS Field Inventory Plugin screenshot

Campaign

Ben Croker also updated his plugin Campaign to leverage soft-deletes, and allow you to permanently delete Contacts for GDPR reasons.

Craft CMS Campaign Plugin screenshot

How to implement soft-delete

Soft Delete will automatically work for any custom elements in Craft. But, if you want to allow users to be able to restore soft-deleted elements from the Control Panel, you need to implement a Restore Action on your element class. For more information, check out the documentation.


Further reading


Further reading