What you need
- Statamic 6.20 or later, on PHP 8.3 or later.
- Composer on the server or in your deployment.
- Statamic Core or Pro. Roles and permissions are a Pro feature, so on Core only the super admin uses the trash.
Install
- In the folder where your site is installed, run:
composer require karelialabs/statamic-trash
- Buy a licence on the Statamic Marketplace and attach it to your site in your statamic.com account, as with any paid addon. Local and staging copies of the site need no licence.
That is all. Trash appears under Tools in the Control Panel, and from now on deletions are kept.
What goes to the trash
| Type | What is kept | Restored |
|---|---|---|
| Entries | Every field, slug, date, publish state, blueprint, author, and the place in the page tree with its child pages | In the same place in the tree. Child pages that Statamic moved up when the page was deleted go back under it |
| Localizations | Each translation of an entry, grouped with the original | Restoring a translation brings back its original first |
| Taxonomy terms | The term in every site | With its data in every site |
| Assets | The file itself and its alt text and other fields, up to a size you set (100 MB by default) | In the same folder. If the file name is taken, as name-restored.jpg |
| Global sets | The set and its values in every site | With all its values |
| Form submissions | Every value the visitor entered | In the same form, with its original date |
| Users (off by default) | Email, name, roles, groups and profile fields. Never passwords, passkeys or two-factor secrets | Without a password. Send a reset from the user page |
Items deleted together, such as an entry and its translations or every asset in a deleted folder, are grouped and can be restored in one go.
Restore something
- Open Tools → Trash.
- Find the item. Search by title, filter by type, or sort by when it was deleted.
- Click the title to see a preview: the fields, the image, the submission, who deleted it and when.
- Choose Restore. To restore many at once, select them and use the bulk action.
Nothing is ever overwritten. If the slug has been taken by a new entry since, the restored one gets a number (about-us-2), and you are told. If the original was restored meanwhile, the trash says there is nothing to restore.
Delete for good
- Delete Forever removes selected items now.
- Empty Trash removes everything you are allowed to see.
- Items older than the retention period (30 days by default) are removed automatically, by Laravel's scheduler once a day and whenever the trash is opened. If your site does not run the scheduler, nothing breaks: the trash tidies itself on the next visit.
Settings
Open Tools → Addons → Trash → Settings, or the Settings button on the trash page.
| Setting | Default | What it does |
|---|---|---|
| Keep items for | 30 days | 0 keeps items until the trash is emptied |
| Types | Everything but users | Switch types on or off |
| Largest asset | 100 MB | Bigger files are deleted as usual, and 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, such as S3, on sites with more than one server |
path | statamic-trash | Folder on that disk |
exclude | none | Collections, taxonomies, asset containers, global sets or forms never to keep |
on_failure | allow | If the trash cannot be written: allow deletes anyway and logs the error, block stops the deletion |
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, for example entries in collections they have view access to |
| Restore items | Restore. Also needs the right to create that kind of item, such as create blog entries 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.
Dashboard widget
To show the latest deletions on the dashboard, add the widget to config/statamic/cp.php:
'widgets' => [
['type' => 'trash', 'width' => 50, 'limit' => 5],
],
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
Good to know
- Only deletions made through Statamic are kept: the Control Panel, your own code or addons, or a collection being deleted. Files removed directly on disk or by git are not.
- The trash is not a revision history. That is Statamic Pro's job. The trash keeps the last saved version of what was deleted.
- 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, Statamic kept those translations as separate entries, so only the original is in the trash.
- It works with flat files and with the Eloquent driver.
Privacy
Trashed form submissions and users still hold personal data until they expire or are deleted. Use a short retention period, Delete Forever or the exclude option to match your privacy policy. The privacy policy and the security page list exactly what is stored.
Remove the addon
composer remove karelialabs/statamic-trash
The stored items stay in the trash folder (storage/app/private/statamic-trash by default) until you delete it.
Need help?
See the support page, or write to the support address there with your Statamic version and the addon version.