=== Elevoire Media Cleaner ===
Contributors: elevoire, hassanraza
Tags: media cleaner, clean media, unused media, media library, duplicate images
Requires at least: 6.5
Tested up to: 7.1
Requires PHP: 8.0
Stable tag: 1.0.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Identify unused, duplicate, and oversized media. Analyze your library and get clear insights without automatic deletions.

== Description ==

**Elevoire Media Cleaner** helps WordPress administrators understand what is in their media library and why certain files might be consuming unnecessary storage.

The plugin analyzes your media library and clearly reports:

* Media files that do not appear to be referenced anywhere
* Duplicate files detected by content hash
* Oversized files that may be affecting site performance
* Missing files (records in the database where the physical file no longer exists)
* Total storage consumption broken down by file type

**The core philosophy is: Analyze first. Explain clearly. Never make destructive changes unexpectedly.**

The plugin is entirely read-only. It does not delete files, modify posts, or change any content on your site. You remain in control of every decision.

= Free Features =

**Media Library Audit**
Scan your full media library and collect detailed information about every attachment: file name, type, size, dimensions, upload date, and usage status.

**Unused Media Detection**
Detect media files that do not appear to be referenced by any content. The scanner checks post content, featured images, site options, post/page meta, nav menus, and Gutenberg block data. Results are classified as:

* In Use — references detected
* Likely Unused — no supported references found
* Possibly Used — uncertain

Files marked as "Likely Unused" should always be reviewed before taking any action. A file can be used by theme code, custom plugins, CSS, JavaScript, or external systems that this scanner cannot detect.

**Duplicate File Detection**
Find files with identical content using a file hash comparison. Duplicates are grouped so you can compare them and decide which copies to keep.

**Large File Detection**
Flag media files that exceed a configurable size threshold (1 MB, 2 MB, 5 MB, or 10 MB). Large images receive a recommendation to compress or replace them.

**Media Statistics Dashboard**
See a clean overview of your library: total file count, total storage, file type breakdown, and counts for unused, duplicate, and large files.

**Media Audit Table**
A searchable, filterable, and sortable table of all scanned media. Filter by type, usage status, or size. Sort by name, size, date, or type. Paginated to handle large libraries.

**Detailed Media Information**
Click any file to see a detailed audit panel: file info, dimensions, upload date, detected usage signals, and the reason the file was flagged.

**Recommendations**
Plain-language, informative recommendations for each flagged file. Recommendations explain what was found and why — never aggressive or alarmist.

**Batched Scanning**
The scanner processes your media in batches of 25 to avoid PHP timeouts and server overload. You can pause, resume, and cancel scans at any time.

= Accuracy Notice =

Media Cleaner identifies files that do not appear to be referenced by the content and data it can safely analyze. A file marked as "Likely unused" may still be used by a theme, plugin, custom code, external system, CSS, JavaScript, or another mechanism that this scanner cannot detect. Always review findings carefully before taking any action.

= Privacy =

This plugin collects no analytics, sends no data to external servers, and makes no external HTTP requests. All scanning happens entirely on your own WordPress installation. No account, license key, or registration is required.

= Pro — Coming Soon =

The free plugin is a complete, standalone media auditing tool. A future Pro version is planned to add:

* Safe media deletion workflow with review and confirmation
* Trash and recovery workflow
* Advanced unused-media detection across more content types
* WooCommerce product image usage detection
* Theme and plugin asset usage detection
* CSS and JavaScript reference analysis
* Backup integration before any cleanup action
* Scheduled media scans
* Advanced duplicate detection with visual similarity
* Bulk review and cleanup tools
* Detailed cleanup history and audit log
* Exportable media audit reports
* Priority support

These features are planned and not yet available. Nothing in the free plugin is intentionally withheld — the free version is a fully functional media audit tool.

== Installation ==

1. Upload the `elevoire-media-cleaner` directory to the `/wp-content/plugins/` directory, or install via the WordPress Plugins screen.
2. Activate the plugin from the Plugins screen.
3. Navigate to **Media Cleaner** in the WordPress admin sidebar.
4. Click **Start Scan** to begin analyzing your media library.

== Frequently Asked Questions ==

= Will this plugin delete my media files? =

No. The free version is a read-only analysis tool. It never deletes, moves, or modifies any files or content on your site.

= How accurate is the "Likely Unused" detection? =

The scanner checks multiple sources: post/page content, featured images, site options, post meta, and navigation menus. However, it cannot detect usage in theme templates, custom PHP code, CSS files, JavaScript files, or external systems. Always review "Likely Unused" files carefully before taking action.

= My library has thousands of images. Will the scan be slow? =

The scan runs in batches of 25 attachments per request, so it will not time out on large libraries. The total time depends on your library size and server speed. You can leave the scan page and come back — progress is saved.

= Can I cancel a scan and start over? =

Yes. You can cancel a running scan at any time from the Scan page, then start a new scan.

= Does this work with WooCommerce product images? =

The free version checks standard WordPress attachment references. WooCommerce-specific product image usage detection is planned for a future Pro version.

= Does this work with Elementor, Divi, or other page builders? =

The scanner checks post meta for attachment IDs and URLs, which catches many page builder references. However, serialized or custom field storage used by some builders may not be fully detected. Results should be treated as indicators, not guarantees.

= What happens when I uninstall the plugin? =

The uninstall handler removes only the plugin's own database tables and option keys. It never removes media files, posts, pages, or any user content.

= Does this work on multisite? =

The plugin functions on individual sites within a multisite network. Network-wide management is not currently supported.

== Screenshots ==

1. Dashboard — media health overview with storage statistics
2. Scan — start, monitor, and resume batched media scans
3. Media Audit — searchable and filterable table of all scanned files
4. Duplicate Groups — files grouped by identical content
5. Large Files — oversized media with recommendations
6. Media Detail Panel — per-file audit with usage signals and recommendations
7. Recommendations — actionable suggestions grouped by type

== Changelog ==

= 1.0.0 =
* Initial release
* Media library audit with batched scanning
* Unused media detection with multi-signal analysis
* Duplicate file detection by content hash
* Large file detection with configurable threshold
* Missing file detection (records with no physical file)
* Media statistics dashboard
* Searchable, filterable, sortable media table
* Detailed per-file audit panel
* Plain-language recommendations
* Settings page for threshold configuration
* Secure AJAX scan workflow
* Full uninstall cleanup

== Upgrade Notice ==

= 1.0.0 =
Initial release.

