Life doesn’t always give you a CTRL + Z. When you delete content in Drupal, it’s gone for good - no undo-ing it. Not always ideal. Sometimes you just want a safety net, a Recycle Bin-style way to undo an accidental delete or bring something back before it’s wiped out forever.

Thanks to the Drupal Trash Module, you now have an option to delete soft. It gives Drupal a powerful internal “trashcan” system, allowing entities to be soft-deleted and then purged (permanently deleted) when you’re absolutely sure. This way, you can maintain full control and consistency across the system.

Come, let’s dig in deeper and learn more about this handy Drupal module.

How the Trash module works

The Drupal Trash module allows you to add an internal field - d e l e t e d to each trash-enabled entity type. End users cannot see this field as it’s completely internal. 

• You can store the Unix timestamp of the entity's soft deletion in the d e l e t e d field.
• An empty field means an active entity (not trashed).
• If it has a timestamp, the entity is trashed.
• You can delete the entity permanently (purge) after a configurable delay.

Be mindful that pressing “Delete” on any entity form doesn’t actually remove it. Instead, the module establishes the current time for the d e l e t e d timestamp.

This lightweight mechanism ensures that deleted entities are only soft-deleted until you decide otherwise.

How trashed entities disappear from everywhere

If the entity isn’t truly deleted yet, how does it vanish from all listings, Views, and content displays?

The Trash module cleverly uses several layers of integration:

• Entity Access Hook: Prevents unauthorized users from directly accessing trashed entities.
• Entity Query Alteration: Filters out trashed entities from default listings.
• Views Query Alteration: Ensures trashed entities don’t appear in Views displays.
• Entity Loading Override: Stops trashed entities from being loaded unless explicitly requested.

These mechanisms work the same across all entity types, making the module consistent and reliable for nodes, taxonomy terms, paragraphs, and more.

How the Trash module achieves this

Drupal usually removes an entity immediately once you delete it via $entity->delete(). However, no single hook or event is available that can intercept this execution across all entity types.

The Trash module solves this by dynamically replacing an entity’s storage class.

Here’s a step-by-step breakdown

1. Implements hook_entity_type_alter().
2. Dynamically generates a new storage class for each trash-enabled entity type using Twig templates.
3. This new class extends the original storage class but overrides the delete() method.
4. Instead of deleting, it sets the $entity->deleted timestamp.

This ensures that no module or developer can bypass the trash system — even if they use $entity->delete() directly.

Currently, this approach works best with SQL-based entity storage classes.

Inside the Trashcan: The “Trash Context”

The Trash module uses a global concept called “trash context”, which is a static variable in the TrashManager service that controls its operational mode.

It has three possible values:

The module can automatically switch contexts based on route options, allowing you to view trashed entities or delete them permanently from specific admin pages.

Handling custom queries

If you’re writing a custom entity query, and you explicitly add a condition on the deleted field yourself, the Trash module detects that and backs off, letting your query run untouched.

This gives developers full control and avoids conflicts in custom logic.

Impact on custom code

In most cases, the Trash module works transparently and won’t affect your custom code. Nevertheless, make sure that:

• The entity is compatible with the Trash’s generated class in the case of a custom storage class.
• Trash overrides the access handler for nodes - make sure any custom handler you use extends the Trash module’s class to keep permissions consistent.

Otherwise, your existing CRUD operations continue to work the same - only deletions become reversible.

Configuration & usage

Take a look at how you can install and use the Trash Module effectively on your Drupal website:

Step 1: Install the Module

You can install it via Composer:

composer require drupal/trash

Then enable it through the Drupal admin UI or using Drush:

drush en trash -y

Step 2: Enable Trash Support for Entities

Once installed, go to:

Configuration → Content Authoring → Trash Settings

Here you can:

• Enable “trash” support for specific entity types (like nodes, media, or paragraphs).
• Set purge delay - how long trashed entities remain before being permanently deleted.
• Define access permissions (who can view, restore, or purge trashed entities).

Step 3: Deleting and Restoring Entities

After enabling Trash:

• When you click “Delete”, the entity moves to the Trashcan, not removed immediately.
• You can access the Trashcan view (usually at /admin/content/trash) to review trashed entities.
• Next, you can restore or permanently delete (purge) them.

Step 4: Automating Cleanup

You can configure cron to automatically purge trashed entities after a certain time.

Or use Drush commands for manual cleanup:

drush trash:purge

This command permanently deletes all trashed entities whose purge delay has expired.

Step 5: Developer Usage

Developers can also interact with Trash programmatically:

use Drupal\trash\TrashManager;

// Soft-delete a node
$trash_manager = \Drupal::service('trash.manager');
$trash_manager->trash($node);

// Restore a trashed entity
$trash_manager->restore($node);

// Permanently purge trashed entities
$trash_manager->purge();

This makes it easy to integrate soft-deletion logic into your own modules or workflows.

Why the Trash module matters

Drupal does not have a regular “trash bin” system. Once you delete an entity, it is permanently deleted unless you have a backup. The Trash module brings several key benefits:

• Safety: No accidental loss of data.
• Recoverability: Restore entities before permanent purge.
• Consistency: Maintain uniformity across all entity types.
• Flexibility: Configure retention and permissions easily.

Final thoughts

The Drupal Trash module brings an evolutionary lift to content safety and site management. Now you can intercept delete operations and manage entity visibility smartly with this module’s soft-delete system, which offers full recovery control.

Site builders, content editors, or developers - the Trash module makes it easier for all to maintain a cleaner, safer, and more accountable content lifecycle. And if you ever need help fine-tuning your Drupal setup or building something more tailored, our Drupal team’s always ready to step in. Check out our Drupal development services today!