=== CoffeeWP Media Cleanup – Scan and Remove Unused Media and Orphan Thumbnails ===
Contributors: eliehanna
Tags: media, cleanup, thumbnails, optimization, attachments
Requires at least: 5.8
Tested up to: 7.0
Requires PHP: 7.4
Stable tag: 1.3.2
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Step-by-step wizard to clean unused media, orphan thumbnails, and broken attachments — safely, with one-click restore.

== Description ==

CoffeeWP Media Cleanup helps you reclaim disk space and tidy up your WordPress media library without risking data loss. Every destructive action moves files to an internal trash so you can recover anything you did not mean to delete.

A guided three-step wizard walks you through the work:


1. **Pre-scan settings** — review detected page-builder compatibility, pick which thumbnail sizes WordPress should generate, and choose a batch size that fits your server.
2. **Scan** — walk your uploads tree and detect which files are unused, broken, or missing.
3. **Results** — see what is unused, what is broken, what is missing, which thumbnails are stale, and run targeted clean actions on selected rows or across the whole result set.

**Clean actions:**

* Delete unused media (file moves to trash; attachment record soft-deleted).
* Delete missing files (clears DB rows whose backing file is gone).
* Delete broken-link records (clears attachment posts whose files never existed).
* Delete orphan thumbnails (removes derivative files with no attachment parent).
* Regenerate missing thumbnails (re-runs WordPress's image-size pipeline).
* Add orphan files to the Media Library (creates attachment records for unattached files).

**Trash + restore:**

A dedicated Trash view lists every file the plugin has moved out. Restore any item with one click, permanently delete individual rows, or empty the trash. Optional auto-delete after N days. Trashed files live under `wp-content/uploads/cwpm/trash/` and are protected from being overwritten by new uploads (filename collisions are detected and avoided).

**Activity log:**

Every clean action writes to a daily log file at `wp-content/uploads/cwpm/logs/`. The Logs view shows each file with size and download link. Optional auto-delete after 30 days.

**Designed to be safe:**

* Soft-delete by default — no file is ever permanently removed except via the explicit "Empty trash" or "Permanent delete" controls.
* Per-row checkboxes and a typed-confirmation disclaimer modal gate the destructive actions.

== Installation ==

1. Upload the plugin folder to `/wp-content/plugins/coffeewp-media-cleanup/`, or install from the WordPress Plugins screen.
2. Activate **CoffeeWP Media Cleanup** from the Plugins screen.
3. Open **Media Cleanup** in the WordPress admin sidebar.
4. Step through Pre-scan settings → Scan → Results. The first scan may take several minutes on large libraries; the wizard reports progress and resumes if your browser times out.

== Frequently Asked Questions ==

= Does this plugin modify original media files? =

No. Originals are never altered. Files marked unused are moved to `wp-content/uploads/cwpm/trash/` and can be restored. Cleanup actions only remove derivative thumbnails or trash unused files.

= What happens when I delete an "unused" file? =

The file moves to `wp-content/uploads/cwpm/trash/<year>/<month>/<filename>` and the attachment's `post_type` changes to `cwpm-trash` (it disappears from the Media Library but still exists in the database). Restore from the Trash view to undo. Permanent delete only happens via "Empty trash", "Permanent delete" on a single row, or the auto-delete-after-N-days setting if you enable it.

= How is "unused" detected? =

The scanner inspects post content (including Gutenberg blocks, the classic editor, post excerpts), post meta (serialized + JSON arrays), widget content, theme support (custom logo, site icon, header / background image), WooCommerce product images and gallery IDs, and `wp-image-N` CSS classes. WPML / Polylang translations resolve back to the original attachment.

= Will it slow down my site? =

The scanner runs only when you trigger it from the admin wizard — no work happens on the public site or in cron. Each scan request is batched (default 50 files per request) to stay within typical PHP execution limits; the batch size is configurable.

= Will deleting the plugin remove all my data? =

By default, no. Uninstalling the plugin from the Plugins screen preserves the custom tables, options, and the `wp-content/uploads/cwpm/` folder so an accidental delete is recoverable. To opt into a complete teardown on uninstall, enable "Delete data on uninstall" in the plugin settings before deleting.

== Screenshots ==

1. Pre-scan settings step — pick thumbnail sizes, set batch size, see page-builder compatibility.
2. Scan step — live progress as the wizard walks the uploads tree.
3. Results step — stats grid, sortable / filterable table, batch action bar.
4. Actions modal — pick which clean actions to run on the selected rows, with safety disclaimer.
5. Trash view — listing of moved files with restore + permanent-delete controls.
6. Logs view — daily activity log files with download links.

== Changelog ==

= 1.3.2 =
* First public release.

== Upgrade Notice ==

= 1.3.2 =
First public release.

== External Services ==

This plugin does not connect to any external services. No data leaves your WordPress install.

== Third-Party Libraries ==

The plugin bundles these GPL-compatible libraries (LICENSE files shipped alongside each):

* **Color Punch** (MIT) — internal CSS / JS UI framework. Shipped at `assets/vendor/color-punch/`.
* **Font Awesome Free** (CC BY 4.0 icons + SIL OFL 1.1 fonts + MIT code) — icon font. Shipped at `assets/vendor/font-awesome/`. Upstream: https://fontawesome.com/
* **Rubik**, **Outfit**, **Fira Code** fonts (SIL OFL 1.1) — bundled with Color Punch under `assets/vendor/color-punch/fonts/`.
* **Catppuccin** color palette (MIT) — applied via Color Punch theme variants. Upstream: https://github.com/catppuccin/catppuccin

== Data + Storage ==

**Custom database tables** (created on activation, dropped only on uninstall when you enable "Delete data on uninstall"):

* `{prefix}_cwpm_scan_results` — per-file scan output (rel_path, attachment_id, usage flags, thumbnail status).
* `{prefix}_cwpm_trash` — trashed-file ledger (rel_path, original_path, file_name, file_size, trashed_at).
* `{prefix}_cwpm_file_hashes` — md5 hashes computed during scan; reserved for future identity-matching features.

**On-disk storage** (under `wp-content/uploads/cwpm/`):

* `wp-content/uploads/cwpm/trash/` — files moved by the trash system. Recoverable until you Permanent-Delete or Empty-Trash.
* `wp-content/uploads/cwpm/logs/` — daily activity logs (one file per day, e.g. `cwpm-2026-05-13.log`).

Both folders contain `.htaccess` + `index.php` stubs to prevent direct web access.

**Options + transients:** all keys start with `cwpm_`. Stored in `wp_options`. Per-user preferences (theme, table density) stored in `wp_usermeta` with the same prefix.

**Custom post type:** `cwpm-trash` — used as a soft-delete state for attachment posts. The attachment record stays in `wp_posts` but is hidden from the Media Library until restored.
