README

A trash bin for Statamic. Product page · Documentation · Support · Security · Privacy · EULA

A trash bin for the Statamic Control Panel. When someone deletes an entry, a taxonomy term, an asset, a global set, a form submission or a user, a copy goes to the trash first. Anyone allowed to can put it back with one click, in the same place it was.

Why

Statamic deletes for good. An entry's revisions are deleted with it, and on sites that store content in a database there is no git history to fall back on. Until now, an editor who deleted the wrong page had to ask a developer to dig it out of a backup.

Features

Everything that can be deleted in the Control Panel: entries (with their localizations), taxonomy terms (all sites), assets (the file itself), global sets (all sites), form submissions and, if you switch it on, users.
Back where it was. A page goes back to the same place in the page tree, with the child pages that Statamic moved up when it was deleted. Slugs, dates, publish state, blueprint and every field are kept.
Deleted together, restored together. An entry and its translations, or every asset in a deleted folder, are grouped so they can be restored in one go. Restoring a translation brings back its original first.
Preview before you restore. See the fields, the image or the submission, who deleted it and when.
Statamic's own listing. Search, filter by type, sort, select many and use the bulk actions Restore and Delete Forever, with the usual keyboard shortcuts.
Safe restores. Nothing is overwritten. A taken slug gets a number, a file name that is in use gets -restored, and you are told about both.
Keeps itself tidy. Items are deleted for good after 30 days (you choose, or keep them forever), and you can empty the trash at any time.
Permissions. Users only see items they could see before they were deleted, and restoring needs the same right as creating that kind of item.
Dashboard widget with the latest deletions.
Works with flat files and with the database (the Eloquent driver), and on any Laravel filesystem disk, including S3 for sites on more than one server.
Command line: php please trash:list, trash:restore and trash:purge.

Requirements

Statamic 6.20 or later
PHP 8.3 or later
Works with Statamic Core and Pro. Roles and permissions are a Pro feature, so on Core only the super admin uses the trash.

Installation

composer require karelialabs/statamic-trash

That is all. Trash appears under Tools in the Control Panel. From now on, deletions are kept.

To show recent deletions on the dashboard, add the widget to config/statamic/cp.php:

'widgets' => [
    ['type' => 'trash', 'width' => 50, 'limit' => 5],
],

Settings

Editors with access can change the most common settings in the Control Panel under Tools → Addons → Trash:

how many days items are kept (0 keeps them until the trash is emptied)
which types go to the trash
the largest asset to keep a copy of (bigger files are deleted as usual, only their details are kept)

Settings saved in the Control Panel take priority over the config file.

Developers can publish the config file for the rest:

php artisan vendor:publish --tag=statamic-trash-config

Option	Default	What it does
`enabled`	`true`	Switch capturing off without uninstalling (`STATAMIC_TRASH_ENABLED`)
`disk`	`local`	Filesystem disk for the trash (`STATAMIC_TRASH_DISK`). Use a shared disk on multi-server sites
`path`	`statamic-trash`	Folder on that disk
`retention_days`	`30`	Days before items are deleted for good
`types`	all but users	What is captured
`exclude`	none	Collections, taxonomies, asset containers, global sets or forms to never capture
`max_asset_size`	`100`	Largest asset (MB) to keep a copy of
`on_failure`	`allow`	If the trash cannot be written: `allow` deletes anyway and logs the error, `block` stops the deletion

Expired items are removed by Laravel's scheduler once a day, and also whenever the trash is opened. If your site does not run the scheduler, nothing breaks: the trash just tidies itself on the next visit.

Permissions

Under Users → Roles there is a new Trash group:

Permission	Lets the user
View the trash	Open the trash. They only see items they could view before, e.g. entries in collections they have `view` access to
Restore items	Restore. Also needs the right to create that kind of item, e.g. `create blog entries`, `upload images assets` or `configure globals`
Delete items forever and empty the trash	Use Delete Forever and Empty Trash

Super admins can do everything. Only a super admin can restore a super admin.

What is stored, and privacy

Items are stored as JSON files (plus the asset file) in storage/app/private/statamic-trash by default. Nothing leaves your server and no database is needed.

A trashed form submission or user still holds personal data until it expires or is deleted. For users, password hashes, passkeys and two-factor secrets are never stored, so a restored user must set a new password (send a reset from their user page). Users are off by default. Use a short retention period, Delete Forever or the exclude option to match your privacy policy.

Good to know

Only deletions made through Statamic are captured (the Control Panel, the API, your own code, or a collection being deleted). Files removed directly from disk or by git are not.
Revision history is not kept. That is Statamic Pro's job. The trash keeps the last saved version of the deleted item.
A deleted collection, taxonomy, container or form is not itself restored. Its entries, terms, assets and submissions are kept, so create it again with the same handle and restore them.
If you chose Detach localizations when deleting a translated entry, those translations were kept as separate entries by Statamic, so only the original is in the trash.

Command line

php please trash:list                 # what is in the trash
php please trash:list --type=entry
php please trash:restore {id} {id}    # restore one or more items
php please trash:purge                # remove expired items
php please trash:purge --all          # empty the trash
php please trash:purge --rebuild-index

Uninstalling

Run composer remove karelialabs/statamic-trash. The stored items stay in the trash folder until you delete it.

Support

Email support@karelialabs.atlassian.net with your Statamic version and the addon version. Questions and bug reports are welcome.

Licence

Commercial. A licence from the Statamic Marketplace covers one production site; development and staging copies are free. See LICENSE.md and the end user licence agreement.

karelialabs / statamic-trash

Package info

Security

Statistics