Download the PHP package sigtrygg-space/kirby-trash without Composer

Kirby Trash

A proper trash can for Kirby CMS: deleted pages and files are not removed instantly but moved to a trash where they can be restored or deleted permanently — via a dedicated Panel area.

How it works

Kirby fires page.delete:before / file.delete:before hooks while the content still exists on disk. This plugin copies the affected page folder (including all languages, files, subpages and Kirby 5 _changes versions) or the file (including all of its content files) into the trash storage and then lets Kirby delete as usual.

If copying to the trash fails (disk full, missing write permissions, …), the exception blocks the actual deletion — your content is never deleted without a safety copy.

Restoring copies the item back to its original location. Parents are looked up freshly (by UUID first, then by id), so renamed parent pages are handled correctly. Content files are restored verbatim, which means UUIDs survive and internal links keep working.

Requirements

• Kirby 5.x
• PHP 8.2+

Installation

Composer

Manual download

Download and extract this repository to site/plugins/kirby-trash.

Git submodule

Panel

The plugin adds a Trash area to the Panel menu (trash icon); the menu entry shows the number of trashed items as a badge. The area lists all trashed items in a table with their original path, size, deletion date and the remaining days until automatic cleanup. Trashed image files show a thumbnail preview, trashed pages the first image of their folder as a cover; other items carry the same type-based icons as Kirby's own file lists. Clicking an item opens its details dialog. Items that are about to expire are highlighted, and the badge switches to the warning color — a last chance to restore before the automatic cleanup removes them. Not sure yet? Every item can be kept longer via its options menu (requires the restore permission): until a date of your choice — prefilled with one more retention cycle — or indefinitely, which protects it from the automatic cleanup and from "Empty trash" (it can still be restored, or removed via its own delete action). Each item can be restored or deleted permanently; the header button empties the whole trash (with a confirmation dialog showing the number of items and total size — indefinitely kept items are spared and listed as such).

On small screens the table is reduced to the most important columns; the options menu of every row therefore also offers a details dialog with all metadata (original path, size, deletion date, deleting user, time left), a large preview for images and page covers, and the restore / delete actions.

Options

Storage location

By default the trash lives in site/storage/trash/, deliberately outside of the content folder and outside of a typical Git deployment flow. If you version your site with Git, add it to your .gitignore:

If the folder is not readable or cannot be created — typically in custom folder setups where the storage location differs — the trash area shows a warning explaining the problem instead of silently appearing empty.

Each trash entry is a folder containing the original data plus a meta.json with the original path, size, deletion date, the deleting user and UUIDs. The metadata carries a version field, and items written by older plugin versions are migrated on read — trash contents survive plugin upgrades.

Automatic cleanup

Expired items are removed whenever the trash area is opened; the area then reports how many items were just cleaned up. So that expired items never pile up invisibly, the menu badge does not disappear when only expired items remain — it turns red and shows their number as a "cleanup required" call to action. Kirby has no native cron; if you want guaranteed cleanup on sites where nobody uses the Panel at all, run the bundled CLI command (requires getkirby/cli) as a cronjob:

Permissions

By default only admins can see and manage the trash. Admins always have access — a custom admin.yml blueprint cannot lock them out accidentally. Other roles can be allowed via their role blueprint:

• access — see the trash area and its contents
• restore — restore items
• delete — delete items permanently / empty the trash

Known limitations

• User files (e.g. avatars) are not moved to the trash; deleting them is permanent, as in plain Kirby.
• Restored pages keep their original folder name including the sorting number; if the sibling sorting changed in the meantime, you may want to re-sort manually.
• If a page or file with the same name has been created in the meantime, restoring fails with a clear error message instead of overwriting.
• The trash works on the filesystem level. In multi-server setups the trash storage must be shared between the servers.

Development

The Panel components live in src/components/ as Vue single-file components and are precompiled with kirbyup — the plugin must not rely on the Vue template compiler, which sites disable following Kirby's security recommendation (and which is deprecated in Kirby 6). After changing them, rebuild the committed index.js / index.css:

The test suite covers the core logic (trashing, restoring, cleanup, retention rules, permission-independent filesystem behaviour).

Note for manual testing: the badge's expiry stats are cached, keyed on the trash root's mtime and item count. Editing a meta.json by hand bypasses that invalidation — touch the trash root (or go through the plugin's API) to see the badge update.

Releasing a new version: bump version in composer.json and date the CHANGELOG in one PR — merging it to main lets the release workflow create the matching tag and GitHub release automatically (with the notes taken from the CHANGELOG, marked as a pre-release while the version is 0.x).

License

MIT