Developers English WordPress Plugin

Media Cleaner for Listeo: Developer Guide

Technical guide for scanner references, quarantine lifecycle, AJAX actions, settings, duplicate detection, disk scans, and safe extension boundaries.

Media Cleaner for Listeo Version 1.0 16 min read Updated Jul 5, 2026

Developer scope. This guide covers safe extensions for Media Cleaner for Listeo: scanner references, quarantine lifecycle, settings, AJAX actions, and operational boundaries. Do not modify license activation, update checks, or entitlement handling.

Architecture overview

The plugin builds a reference graph before marking media as unused. It loads attachments, maps file basenames and URLs, collects references, categorizes items, optionally hashes duplicates, optionally scans disk leftovers, and then builds a structured report.

ScannerLMC_Scanner builds the reference-aware report.

Admin AJAXlmc_scan, lmc_act, lmc_restore, lmc_purge, lmc_export_zip.

QuarantineStores enough data to restore files and attachment metadata.

Cronlmc_purge_expired purges expired quarantine items.

Settings

Option	Purpose
`listeo_media_cleaner_deletion_mode`	Controls whether actions quarantine or delete.
`listeo_media_cleaner_quarantine_days`	Number of days to keep quarantined items before purge.
`listeo_media_cleaner_scan_disk`	Enables leftover file scan in uploads.
`listeo_media_cleaner_hash_dupes`	Enables duplicate detection by hashing files.

Reference coverage

The scanner protects media referenced by WordPress and Listeo structures, including _thumbnail_id, Listeo _gallery, WooCommerce _product_image_gallery, site logo, site icon, theme logo, header image, post content, generic post meta, options, term meta, and user meta where file URLs or image IDs can appear.

AJAX actions

Action	Purpose
`lmc_scan`	Runs a scan and returns a report.
`lmc_act`	Applies selected cleanup action.
`lmc_restore`	Restores a quarantined item.
`lmc_purge`	Permanently purges quarantined items.
`lmc_export_zip`	Exports quarantined media.
`lmc_activate_license`, `lmc_deactivate_license`	Reserved license actions. Do not override.

Safe extension patterns

Add custom reference detection for a builder or plugin before deleting anything it controls.
Run scans from admin-only contexts with nonce and capability checks.
Prefer quarantine for custom cleanup flows.
Keep source files, metadata, and restore data together.
Do not purge automatically on sites without verified backups.

Performance notes

Large media libraries can create high memory usage during scan, serialization, and JSON response generation. Hashing duplicates and scanning disk leftovers are the most expensive options. For very large sites, run during low traffic and consider staged scans.

Regression checklist

Listeo gallery images referenced in _gallery are marked used.
Featured images and WooCommerce gallery images are marked used.
Images referenced by content URLs are resolved back to attachments.
Quarantine restore recreates the expected media state.
Expired purge does not run before the configured retention window.
License and updater code remains untouched.