=== DevDome Safe Media Cleaner ===
Contributors: devdome
Tags: media cleaner, unused images, media library, media cleanup, duplicate images
Requires at least: 6.0
Tested up to: 7.0
Requires PHP: 7.4
Stable tag: 1.0.3
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Find unused, duplicate, orphaned, and missing media files safely with Recycle Bin restore.

== Description ==

DevDome Safe Media Cleaner is a media cleaner that finds unused images in your WordPress media library and helps you delete them safely. It also finds orphaned files sitting in your uploads folder, duplicate images, and broken references, so you can clean up your media library, free up disk space, and speed up your backups with review and rollback protection at every step.

Media cleanup should be careful, reviewable, and easy to undo. Clean your media library with rollback protection and safer defaults.

**Why it is the safe way to delete unused images**

* **Nothing is deleted right away.** Every cleanup lands in the Recycle Bin first. Files are only removed for good when you confirm the permanent delete yourself.
* **One click restore.** Any cleanup batch can be put back exactly where it was, verified file by file with checksums.
* **Last second re-check.** The moment before a file moves, the plugin re-verifies it is still unused. If you used the image a minute ago, it stays.
* **Protected by default.** Recent uploads, WooCommerce product images, page builder images, theme and customizer images, and anything referenced in your settings are never auto selected.
* **Honest labels.** Every image is marked Safe to remove, Needs manual review, or Protected, and the card shows exactly why. Anything uncertain is never selected for you.
* **Optional media backups.** Create a full ZIP backup of your images before cleaning, download it, or restore it later. Restored images are re-registered in the Media Library automatically.

**What it finds**

* Unused images: media library files that no post, page, builder layout, widget, or setting references.
* Orphaned files: images sitting on disk with no Media Library record, leftovers from deleted images, old imports, and other tools. WordPress cannot even see these.
* Duplicate images: exact copies with a suggested keeper. Suggestions only, nothing is ever auto deleted.
* Missing files: Media Library entries whose file has vanished from disk.
* The biggest wins first: sort by file size and free up disk space where it matters most.

**Review everything before you clean**

The Review tab is a visual grid, not a spreadsheet. Switch between Media Library and Disk Storage, search by filename, filter by status, sort by file size, dimensions, or age, flip between grid and list view, and select images in bulk or one by one. Every card shows the thumbnail, size, dimensions, upload date, status badge, and the reasons it was flagged, with direct Edit and View buttons. Export the whole list to CSV if you want it on record.

**How it works**

1. **Scan.** One click scans your whole media library and uploads folder in the background. Scans are chunked and resumable, so they finish even on shared hosting.
2. **Review.** Check the grid, filter and sort, and select only what you trust.
3. **Clean to the Recycle Bin.** Selected files move to a protected folder, not the void. Watch your site for a few days, then restore anything or confirm the permanent delete.

**A deep scan, not a guess**

The scan checks far more places than a typical cleaner: post content across every post type including revisions and reusable blocks, featured images, galleries, Gutenberg blocks, srcset and lazyload attributes, CSS backgrounds, widgets, menus, site logo and icon, and the options table. It reads page builder data from Elementor, Divi, Beaver Builder, WPBakery, Bricks, Oxygen, Kadence, GenerateBlocks, Spectra, SeedProd, and Thrive. It detects WooCommerce product, gallery, variation, and category images, ACF and Meta Box image fields, and Yoast, Rank Math, and AIOSEO social images. All thumbnail sizes and scaled or edited copies are matched back to their originals.

**Built for large media libraries**

Scanning runs in small background chunks with saved progress, pause and resume, and no big memory loads. It scales from a small blog to more than 100,000 attachments without timeouts, and visitors never notice a thing.

**Stays clean on its own**

Turn on scheduled scans and the dashboard numbers stay fresh automatically. Add the unused growth alert and a warning appears in your dashboard when unused media passes a size you choose. Want it watched for you? Connect a free DevDome account and enable DevDome Monitoring: after each scan your aggregate media stats go to DevDome, which tracks growth over time, shows a media-health dashboard for your sites in your account, and emails you an alert when your limit is passed, at a frequency you control so it never spams you.

**Everything you need is free**

Scanning, review, reports, duplicates, the Recycle Bin, restore, media backups, scheduled scans, CSV export, and WP-CLI commands are all free and unlimited. Only one optional extra asks you to connect a free DevDome account: the DevDome Monitoring service, which tracks your media stats over time, shows a media-health dashboard in your account, and emails you alerts when unused media grows past a limit you set.

== External services ==

This plugin works fully offline. It connects to optional DevDome services only when you opt in:

1. **DevDome account connect (devdome.com and api.devdome.com): optional, opt-in.** Connecting a free DevDome account is only needed for the optional DevDome Monitoring service described below. When you choose to connect, the connect flow opens devdome.com in your browser; after you approve it there, the plugin stores your public DevDome Account ID and a site token, and it sends that site token to api.devdome.com to verify the link (the service returns the account email shown in Settings). Only the Account ID, this site's domain, and the site token are transmitted. If you disconnect the account, the plugin sends the site domain and site token to api.devdome.com once to unlink this site. **No media files and no private image URLs are ever sent.** Service provided by DevDome. Terms: https://devdome.com/terms-of-service and privacy: https://devdome.com/privacy-policy

2. **DevDome Monitoring (api.devdome.com): optional, opt-in, requires a free DevDome account.** When you enable Monitoring in Settings, the plugin sends aggregate scan statistics to the DevDome monitoring endpoint after each scan: the site domain, the site token, total media count and size, unused media count and size, orphaned file count, your alert threshold, and your chosen email frequency. DevDome's servers store this history for the media-health dashboard in your devdome.com account, track growth across scans and sites, and compose and send alert emails to your account email address when your threshold is passed. The cross-site history, the dashboard, and the email delivery are processed on DevDome servers; the plugin does not build or send any alert email itself. No media files, filenames, image URLs, or visitor data are ever sent. Service provided by DevDome. Terms: https://devdome.com/terms-of-service and privacy: https://devdome.com/privacy-policy

All scanning, classification, Recycle Bin, and restore run entirely on your own server. No outbound call is made unless you explicitly connect a free DevDome account. Monitoring stats are only sent if you also enable DevDome Monitoring in Settings.

= Dormant endpoints in the bundled DevDome core =

The bundled shared library also references endpoints that are never contacted on this WordPress.org build:

* `https://api.devdome.com/plugin-updates/`: the suite hub's self-hosted install helper. It is disabled on this build; updates and installs come only from WordPress.org.
* `https://api.devdome.com/media-cleaner/metrics`: an aggregate product-metrics ping used only by the DevDome-distributed build. On this build it never runs and no metrics are ever sent.

== Privacy ==

* **Media files:** never leave your server. Scanning and cleanup are 100% local.
* **Recycle Bin:** trashed files are stored locally in `/wp-content/uploads/devdome-safe-trash/`, which is made un-servable (deny-all .htaccess/web.config, index.php silence, noindex header) during the review window.
* **No cookies** are set by this plugin.
* **Metrics:** this build sends no product metrics. The aggregate-metrics ping in the codebase is dormant here and only runs on the DevDome-distributed build.

== Installation ==

1. Install the plugin from the Plugins screen, or upload it to `/wp-content/plugins/` and activate it.
2. Open **DevDome, then Safe Media Cleaner** and click **Scan Media Library**.
3. Review the flagged images, move the ones you trust to the **Recycle Bin**, check your site for a few days, then restore anything you want back or confirm the permanent delete.

== Frequently Asked Questions ==

= Will it delete images that are still used? =
No. The scan checks dozens of locations (posts, page builders, WooCommerce, ACF, SEO images, widgets, theme settings, CSS and srcset, and more) and re-verifies each file the moment before it moves. Anything it cannot confirm is marked Needs manual review and is never selected automatically.

= Can I undo a cleanup? =
Yes. Nothing is deleted on the first action: files move to the Recycle Bin. Each batch can be restored with one click to its exact original location, with an integrity check on every file.

= How do I free up disk space with it? =
Run a scan, open the Review tab, sort by file size, and clean the largest unused images first. The dashboard shows exactly how much space you can reclaim, and orphaned files in the uploads folder often free up the most.

= Does it handle Elementor, other page builders, and WooCommerce? =
Yes. It parses Elementor, Divi, Beaver Builder, WPBakery, Bricks, Oxygen, Kadence, GenerateBlocks, Spectra, SeedProd, and Thrive layout data, and detects WooCommerce product, gallery, variation, and category images, ACF fields, and Yoast, Rank Math, and AIOSEO social images.

= Will it slow my site down? =
No. The scan runs in the background in small chunks and never blocks normal page loads. Visitors are never affected.

= Do I need a DevDome account? =
No. Scanning, review, reports, backups, cleanup, the Recycle Bin, and restore all work without any account, with no limits. Only one optional extra asks you to connect a free account: DevDome Monitoring, which watches your media stats on DevDome servers, shows a media-health dashboard in your account, and emails you alerts.

= Does it work on multisite? =
Yes. Each site in the network keeps its own scans, Recycle Bin, backups, and settings, and uninstalling cleans up every site in the network.

= What exactly is the Recycle Bin? =
A protected folder inside your uploads directory. Cleaned files are moved there (never deleted) together with a per-batch manifest and checksums, so you can browse batches, restore everything with one click, or confirm a permanent delete once you are sure.

== Screenshots ==

1. Dashboard: Media Library and Disk Storage cleaners with live stats, cleanliness score, and one-click actions.
2. Review tab, Media Library: visual grid of unused images with status badges, reasons, and bulk selection.
3. Review tab, Disk Storage: orphaned files on disk that WordPress cannot see, ready to review and clean.
4. Recycle Bin: every cleanup batch listed with its source and status, restorable in one click.
5. Backup and Restore: create, upload, download, and restore ZIP backups of your media.
6. Settings: DevDome Monitoring, scheduling, retention, and protection rules.

== Changelog ==

= 1.0.0 =
* Initial release.
