README

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

composer require sigtrygg-space/kirby-trash

Manual download

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

Git submodule

git submodule add https://github.com/sigtrygg-space/kirby-trash.git site/plugins/kirby-trash

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. 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 for another retention cycle via its options menu (requires the restore permission). 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).

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) and the restore / delete actions.

Options

// site/config/config.php
return [
    // days until items are removed automatically.
    // -1 = keep forever. 0 is treated as invalid and
    // falls back to the default (30), so a misconfiguration
    // can never wipe the trash instantly.
    'sigtrygg-space.kirby-trash.retentionDays' => 30,

    // where trashed items are stored (string or closure).
    // default: site/storage/trash — custom folder setups have
    // to point this at their storage location
    'sigtrygg-space.kirby-trash.root' => null,

    // disable the trash entirely: deletions become permanent
    // again and the Panel area disappears. Also accepts a
    // closure for logic-driven switching, e.g. by environment:
    // 'enabled' => fn ($kirby) => $kirby->system()->isLocal() === false
    'sigtrygg-space.kirby-trash.enabled' => true,

    // show the number of trashed items as a badge on the Panel
    // menu entry. false disables the badge; an array restyles it,
    // e.g. ['theme' => 'passive'] for a more subtle look
    'sigtrygg-space.kirby-trash.badge' => true,

    // items expiring within this many days are highlighted in
    // the table and switch the badge to the warn theme.
    // 0 disables the warn state
    'sigtrygg-space.kirby-trash.warnDays' => 5,
    'sigtrygg-space.kirby-trash.warnTheme' => 'orange',

    // the badge's expiry lookup is cached persistently
    // (site/cache); set to false to disable the plugin cache
    'sigtrygg-space.kirby-trash.cache' => true,
];

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:

site/storage/

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:

kirby trash:cleanup

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:

# site/blueprints/users/editor.yml
title: Editor
permissions:
  sigtrygg-space.kirby-trash:
    access: true
    restore: true
    delete: false

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

composer install --no-plugins
composer test

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:

npm install
npm run build

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

sigtrygg-space / kirby-trash

Maintainers

Package info

Statistics

Security