=== Large Image Finder – Find, Optimize & Clean Up Large Images ===
Contributors: abidpti
Tags: media library, media audit, unused images, large images, media cleaner
Requires at least: 6.5
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 1.0.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Audit your Media Library: find heavy, unused, and missing images, trace exact post and page builder usage, and clean up server space safely.

== Description ==

**Large Image Finder** is a specialized Media Library audit and usage intelligence tool for WordPress. It provides site owners and developers with a complete, transparent overview of media storage: pinpointing oversized files, mapping exactly where every image is embedded across content and page builders, identifying unused orphaned media, and detecting broken attachments.

Unlike generic image compressors that simply batch-process files without context, Large Image Finder solves the underlying media management problem: understanding which images are actually needed, where they live, and which files can be safely optimized or removed to reclaim gigabytes of disk space and boost Core Web Vitals (LCP).

= How Large Image Finder is Different =

* **Deep Media Usage Mapping:** See every place an image is used (posts, pages, WooCommerce product galleries, Elementor, Beaver Builder, Bricks, site logo, icon, and widgets) before touching it.
* **Unused & Orphaned Media Audit:** Detect images not linked to any content so you can safely clean up disk space.
* **Broken File Detection:** Find database attachment records whose physical media files were deleted or lost.
* **100% Local & Private:** No third-party APIs, no monthly subscriptions, and no external servers. Everything runs locally on your own server.
* **Safe On-Demand Optimization with Rollback:** Resize and compress on request using WordPress's built-in image tools, with original files backed up for instant one-click restoration.

= Deep Media Usage Tracking =

* The **Used in** column shows the exact count of places where an image is used and links directly to each post, page, or product edit screen.
* Detects featured images, in-content images, upload parent posts, WooCommerce product gallery images, custom logos, site icons, header images, and widgets.
* Full compatibility with modern page builders including **Elementor**, **Beaver Builder**, and **Bricks**.
* Sort the report by usage count to prioritize high-visibility media first.

= Find Unused & Orphaned Images =

* The **Unused images** tab lists media not referenced anywhere in known content, allowing you to identify clutter without risking broken layouts.
* Review unused media safely and delete unnecessary files permanently with built-in confirmation guards.

= Audit Oversized & Heavy Media =

* Set your own audit threshold: 500 KB (default), 1 MB, 2 MB, or custom KB value. Toggle thresholds instantly without re-scanning.
* View every oversized image with thumbnail preview, exact dimensions (width × height), file size, format, and attachment ID.
* Review disk usage of generated thumbnail sizes and full-size originals.
* Actionable hints: flags overly wide images (e.g. "4,000 px wide — resize to 2,560 px") and heavy formats.

= Detect Missing & Broken Media Files =

* The **Missing files** tab flags Media Library database records whose physical files are missing from the server.

= Local On-Server Optimization (With Backup) =

* On-demand optimization right from the report for single images or bulk selections.
* Resizes images wider than your **Max width** (default 2,560 px) and recompresses them using your configured **Quality** settings.
* Uses the native WordPress image engine (Imagick or GD) — completely free and unlimited.
* Replaces files in-place with identical names and URLs so existing posts and pages automatically serve smaller files without rewriting content.
* Originals are safely backed up to `wp-content/uploads/large-image-finder-backups/` and can be restored at any time. Optionally enable "Delete original after optimizing" if backups are not needed.

= See where each image is used =

* The **Used in** column shows how many places use the image and links to each post, page or product.
* Detects featured images, images inside post and page content, the post an image was uploaded to, WooCommerce product galleries, the site logo, the site icon, the header image and widgets.
* Reads page builder layouts from **Elementor**, **Beaver Builder** and **Bricks**.
* Sort by usage to fix the most visible images first.

= Find unused images =

* The **Unused images** view lists images that are not used anywhere the plugin can check, so you can clean up your Media Library and save disk space.
* Nothing is deleted automatically. You stay in control.

= Find missing image files =

* Lists Media Library items whose file no longer exists on the server (broken images).

= Fast and safe on large Media Libraries =

* Scans in small batches with a progress bar, so even libraries with tens of thousands of images do not time out.
* Interrupted scans can be resumed.
* Safe when the scan is started from two browser tabs.
* After the first scan, the report updates itself when images are uploaded, edited or deleted, and when posts are saved.

= Search, filter, export =

* Search by file name.
* Filter by format (JPEG, PNG, WebP, GIF…), minimum file size, minimum width and minimum height.
* Sort by file size, file name, width, usage or ID. Show 20 or 50 images per page.
* Export the report — or only selected images — to a CSV file for Excel or Google Sheets. Exports are protected against spreadsheet formula injection.
* Step through selected images in the built-in WordPress image editor, one after another, to scale them down yourself.

= Everywhere in your admin =

* A **File size** column in Media → Library, highlighted when an image is over your threshold.
* A **Dashboard widget** with the number of large, unused and missing images.
* An **upload warning** when someone uploads an image larger than your threshold. The upload itself is never blocked.
* A **scan history**, so you can watch the number of large images go down.

= Free, private and lightweight =

* 100% free. No API key, no account, no upsell.
* No external requests. Your data never leaves your site.
* Adds no scripts, styles or database queries to your front-end pages.
* Multisite compatible.
* Translation ready.

== Installation ==

1. In your WordPress admin, go to **Plugins → Add New** and search for "Large Image Finder".
2. Click **Install Now**, then **Activate**.
3. Go to **Media → Large Image Finder** and click **Start scan**.

Manual installation: upload the `large-image-finder` folder to `/wp-content/plugins/` and activate the plugin from the **Plugins** screen.

== Frequently Asked Questions ==

= How do I find large images in WordPress? =

Install and activate the plugin, open **Media → Large Image Finder** and click **Start scan**. All images larger than your threshold (500 KB by default) are listed, largest first.

= What is a good maximum image size for a website? =

For most photos, 100–300 KB is a good target, and anything above 500 KB is worth checking. Hero and background images can be a little larger. Start with the 500 KB default and lower it as you optimize.

= How do I find unused images in the Media Library? =

After a scan, open the **Unused images** view. It lists images that were not found in posts, pages, featured images, page builder layouts, WooCommerce galleries, widgets, the site logo or the site icon.

= Is it safe to delete the images in the "Unused images" list? =

Not automatically. Images can also be used in places no plugin can see reliably — theme files, CSS, custom fields of other plugins, emails or other websites. Check each image and always keep a backup before deleting. Large Image Finder never deletes Media Library items.

= How do I optimize (compress) large images? =

In the report, hover over an image and click **Optimize**, or select several images and choose **Bulk actions → Optimize selected**. Set the maximum width and quality in the **Optimization** box first.

= Does optimizing change my images? =

Only when you click **Optimize**. Scanning never changes anything. When you optimize, the image file is replaced by a smaller version with the same name, and the original is saved as a backup unless you turned on **Delete the original after optimizing**.

= Where are the originals stored, and how do I restore one? =

In `wp-content/uploads/large-image-finder-backups/`, in the same year/month folders as your uploads. Click **Restore original** under the image in the report to put it back. Deleting an image from the Media Library also deletes its backup.

= Do I need to update my posts after optimizing? =

No. The optimized image keeps the same file name and URL, so every post, page and widget that uses it shows the smaller file straight away. If a page still shows the old size, clear your page cache or CDN cache.

= Does optimizing need an API key or an external service? =

No. Images are processed on your own server with the image library WordPress already uses (Imagick or GD). There are no limits and no data is sent anywhere.

= Which formats can be optimized? =

JPEG, PNG and WebP, when your server's image library supports them. GIFs are skipped so animations are not lost. Only the main image file is optimized; the generated thumbnail sizes are already small.

= Will it slow down my website? =

No. The plugin adds nothing to your front-end pages. Scans run in small batches from the admin page, and the report is only updated when media or posts are changed.

= Does it work with Elementor, WooCommerce and other page builders? =

Yes for Elementor, Beaver Builder, Bricks and WooCommerce product galleries, and for any builder that stores images in the post content (such as Divi and WPBakery). Builders that store layouts elsewhere may show some images as unused.

= Which file size is reported? =

The size of the main image file WordPress serves (for big uploads, the "-scaled" version). The space used by the generated sizes and the unscaled original is shown below it but does not count towards the threshold.

= Images stored on Amazon S3 or another cloud service are listed as missing. Why? =

The plugin only scans files stored on your own server. Cloud storage (offloaded media) is not supported yet.

= Who can use the plugin? =

Administrators (users with the `manage_options` capability). The File size column and the upload warning are also shown to other users who can upload media.

= What is removed when I uninstall the plugin? =

All plugin settings, the scan history and the scan results, on every site of a multisite network. Your images are not affected. Backups of optimized images in `uploads/large-image-finder-backups/` are kept, because they are your original files — delete that folder yourself if you no longer need them.

= Can I change the scan speed? =

Developers can use these filters:

* `large_image_finder_batch_size` — images per request (default 50).
* `large_image_finder_batch_time_limit` — seconds per request (default 10).
* `large_image_finder_max_useful_width` — width in pixels above which a resize is suggested (default: the Max width setting).

== Screenshots ==

1. Scan, size threshold and summary cards: large, unused and missing images at a glance.
2. Large images report with file size, dimensions, usage and optimization suggestions.
3. One-click Optimize with before/after size, Restore original and Delete backup.
4. Optimization settings: max width, quality and backup option.
5. "Used in" column showing every post and page that uses an image.
6. Unused images view.
7. Filters, bulk actions and CSV export.
8. File size column in Media → Library.
9. Dashboard widget.

== Changelog ==

= 1.0.0 =
* First release.

