Media Library Cleaner

Description

Version 2.0 is a ground-up rebuild from the original release, with a new scanning architecture and admin interface.

How The Scanning Engine Works
Unlike lightweight scanners that only check the post_content column, Media Library Cleaner performs a deep inspection across your entire WordPress architecture. When a scan is initiated, every attachment in the media library is checked against:
Core Content: Standard post content and Gutenberg block editor attributes.
Post Meta: All custom fields and metadata, including complex data structures generated by Layout & Design plugins like Elementor and Beaver Builder.
Theme Settings: Theme mods, site icons, custom logos, and custom header images.
Taxonomies & Users: Term meta and user meta fields.
Widgets: Media widgets deployed across sidebars and footers.
Scan Options: Administrators can explicitly choose whether to include or ignore draft posts and post revisions during the reference check.
Batched Processing Architecture
To handle enterprise-scale WordPress installations, the scanning engine uses batched processing. Instead of loading the entire database into memory, the plugin queries and processes content in strict batches. This architecture prevents PHP memory exhaustion and server timeout errors – and has been thoroughly stress-tested on environments containing over 60,000 posts.

A live four-phase progress bar tracks the execution in real-time, displaying counts for:
Initialisation
Post scanning
Metadata scanning
Results loading
Once the scan completes, results are loaded into a split-view dashboard separating Unused Files from Used Files.
Used Files View: Explicitly lists the specific posts, pages, or settings where an attachment is currently referenced, giving you absolute certainty about why a file was flagged as active.
Progressive Card Grid: Files are displayed in a visual grid showing the image thumbnail (or a specific file type icon for non-images), filename, file type, file size, exact pixel dimensions, and upload date.
Sticky Selection Bar: A persistent control bar tracks the total number of selected files and calculates their combined file size in real-time, allowing you to see exactly how much server space you are about to reclaim. Includes bulk select/deselect controls.
One-Click Selection: Clicking anywhere on a progressive card toggles a highly visible selected state (blue border and checkmark overlay).
Deletion Mechanics & Safety Protocols
Media Library Cleaner treats data destruction with the utmost caution. A prominent backup warning is displayed before any scan or deletion sequence can be initiated.
WordPress Capability Checks: Before attempting to remove any file, the plugin performs a strict, per-item capability check. Deletion requests are automatically refused for any file the current user does not have explicit permission to delete.
Confirmation & Permanence: A WordPress-native confirmation modal intercepts the deletion trigger, explicitly warning the user that deletions are permanent (unless the MEDIA_TRASH constant is enabled in wp-config.php).
Batched Deletion: Much like the scanning process, file deletion is handled in batches with a live progress indicator.
Post-Deletion Reporting: A completion modal provides a definitive summary, explicitly detailing how many files were successfully deleted and how many failed.
Per-File Reporting: Every individual file is reported as a success or a failure, with specific technical reasons provided for any failed deletions.
Persistent Logging & Environment Data
Database Session Logs: Every deletion run is permanently recorded in the database. This log records the timestamp, the user who initiated the action, the total file count, and the explicit success/failure results for every individual file processed during that run.
Environment Info Tab: A dedicated diagnostic tab provides administrators with critical context before running a scan. It displays the total media count, the physical size of the uploads folder, a list of all registered image sizes, the precise uploads directory path, directory writability status, media trash status, and current PHP/WordPress environment details.
Installation
Upload the media-library-cleaner folder to the /wp-content/plugins/ directory.
Activate the plugin through the ‘Plugins’ menu in WordPress.
Navigate to Tools – Media Library Cleaner in the WordPress admin menu.
Review the Environment Info tab and perform a full site backup.
Configure your Draft and Revision scan options, then click Run Scan.
Frequently Asked Questions
Will this plugin cause PHP memory errors on large sites?
No. Media Library Cleaner utilizes a batched scanning architecture that processes database queries in chunks. This prevents the server from loading massive datasets into memory simultaneously, preventing timeout errors. It has been tested against databases with 60,000+ posts.

Does it support modern Layout & Design plugins?
Yes. The metadata scanner explicitly checks complex data arrays generated by Layout & Design builders such as Elementor and Beaver Builder, ensuring assets embedded within builder modules are correctly identified as “in use”.

Are deleted files recoverable?
By default, WordPress permanently removes media files when deleted. Media Library Cleaner respects this core behaviour. However, if you have defined define( ‘MEDIA_TRASH’, true ); in your wp-config.php file, deleted files will be moved to the Media Library Trash rather than being permanently destroyed.

Why do some files fail to delete?
The plugin enforces strict WordPress capability checks on a per-item basis. If your user role lacks the required permissions to delete a specific attachment, or if the server directory lacks the necessary write permissions, the deletion will be refused. The exact reason for the failure is recorded in the persistent session log.

What information is stored in the persistent session log?
The log records the timestamp of the deletion run, the ID of the user who executed it, the total number of files targeted, and a granular breakdown of which specific files succeeded or failed (including the failure reason).