=== Smart Media Cleanup ===
Contributors: marketupmedia
Tags: media, media library, folders, cleanup, orphan
Requires at least: 6.0
Tested up to: 6.8
Stable tag: 1.1.0
Requires PHP: 7.4
License: GPL v2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Automatically delete unused media when posts are removed, organise your library with virtual folders, and clean up orphan attachments in bulk.

== Description ==

Smart Media Cleanup keeps your WordPress media library clean and organised.

**Auto-delete on post deletion**
When a post (or WooCommerce product, or any custom post type) is permanently deleted, the plugin automatically deletes its attached media — featured image, images attached via post_parent, and images referenced in custom meta fields (galleries). A built-in safety check ensures that images used by other posts are never deleted.

**Virtual folders in the Media Library**
A folder panel appears inside the WordPress Media Library (grid view). Folders are automatically built from your post types — each CPT gets its own top-level folder, with sub-folders for every post. Images are auto-assigned to their post's folder when a post is saved.

* Browse images by folder with one click
* Create, rename, and delete folders via a clean modal — no browser popups
* Search folders by name (useful when you have hundreds of folders)
* Drag and drop images from the grid onto any folder to reassign them
* Select multiple images (bulk mode) then click a folder to move them all at once
* "Sync All Posts to Folders" button for retroactive assignment of existing media

**Bulk orphan cleanup**
A dedicated admin page scans your media library for attachments that are not used anywhere and lets you review and delete them in bulk. The scanner runs in batches so it never times out on large libraries.

**Smart usage detection**
Before deleting any image, the plugin checks all the places WordPress and popular plugins store image references:

* Featured images
* Post content and short descriptions (including imported content)
* Custom meta fields (galleries, custom post types)
* Elementor page builder data
* Yoast SEO and RankMath social images (auto-detected)
* WordPress site logo, header image, site icon
* JetEngine and other custom field plugins (via configurable meta keys)

**Safety first**
Every deletion is irreversible. The plugin includes multiple safety layers: a "check usage" option that prevents deleting shared images, confirmation dialogs before bulk deletion, and a detailed activity log with automatic retention cleanup.

== Installation ==

1. Upload the `smart-media-cleanup` folder to `/wp-content/plugins/`
2. Activate the plugin from the **Plugins** menu
3. Go to **Media Cleanup → Settings** and configure which post types to monitor
4. Add any custom meta field keys that store image IDs (e.g. gallery fields from JetEngine, ACF, etc.)
5. Use **Media Cleanup → Orphan Cleanup** to scan and remove unused attachments

== Frequently Asked Questions ==

= Will this delete images that are used on multiple posts? =

No. The "Check usage before deleting" option (enabled by default) prevents deleting any image that is referenced by another post, page, or anywhere else on the site. We strongly recommend keeping this option enabled.

= What happens if I delete a post by mistake? =

If the trigger is set to "On permanent delete only" (the default), moving a post to Trash does not delete its media. You can restore the post from Trash and everything is intact. Only when you permanently delete from Trash will media be removed.

= Does it work with WooCommerce? =

Yes. It monitors WooCommerce products the same as any other post type. Add `_product_image_gallery` to the meta field keys in Settings to also clean up product gallery images. WooCommerce variation images are also handled when a product or variation is permanently deleted.

= Does it work with Elementor? =

Yes. The plugin automatically checks Elementor's page data for image references, so images used in Elementor layouts are never flagged as orphans.

= Does it work with Yoast SEO or RankMath? =

Yes. Both plugins are auto-detected. Images set as OG or Twitter social images are automatically protected from deletion — no configuration needed.

= What about imported content? =

The plugin searches post content by CSS class, full URL, and URL path (without domain) to handle cases where imported content has HTTP/HTTPS mismatches or old domain references.

= Can I use virtual folders without the auto-delete feature? =

Yes. Each feature can be enabled or disabled independently in Settings.

= Does the folder panel work in list view? =

The folder panel is available in Media Library grid view. List view support is planned for a future release.

= Is there a way to recover deleted files? =

No. File deletion is permanent. Always make a backup before running bulk cleanup on a production site.

= Does it work on multisite? =

The plugin does not break on multisite, but there is no per-site network UI in this version. Each site in the network manages its own media independently via the standard WordPress admin.

== Screenshots ==

1. Settings page — configure post types, meta fields, trigger, and safety options
2. Orphan Cleanup — scan results with thumbnails, file size, and bulk delete
3. Activity Log — history of all deletions with event filter and date range

== Changelog ==

= 1.1.0 =
* Added virtual folder panel in Media Library — browse images by CPT and post
* Added drag and drop — drag any image from the grid onto a folder to reassign it
* Added bulk assign — select multiple images in bulk mode, then click a folder to move them all at once
* Added folder search — filter folders by name instantly (no page reload)
* Added "Sync All Posts to Folders" bulk tool for retroactive folder assignment
* Added folder CRUD (create, rename, delete) via custom modal — no native browser dialogs
* Added WooCommerce variation image cleanup — variation images are deleted when a product or variation is permanently deleted
* Fixed settings being lost when plugin is updated (new defaults are merged without overwriting existing values)

= 1.0.0 =
* Initial release
* Auto-delete attachments on post permanent deletion
* Safety check: skip attachments used elsewhere
* Bulk orphan cleanup with batched AJAX scanning
* Activity log with automatic retention cleanup
* Auto-detection of Elementor, Yoast SEO, RankMath, and Minorank
* Support for JetEngine, WooCommerce, and custom meta field keys
* Confirmation dialogs and caution notices for all irreversible actions
