Description
This version replaces the original public-trash approach with manually reviewed private quarantine and recovery. Back up the database, uploads and existing trash before upgrading. Scan results are review candidates, not proof that a file is unused. Test on a staging copy before using it on an important site. Very large media libraries and every third-party integration have not been independently benchmarked.
Gerdoo indexes registered attachment files and supported database references before listing review candidates. A missing reference is not proof that a file is unused. Review custom code, external uses and integrations before quarantine.
- JSON and inert PHP serialized-array/object parsing, numeric IDs, gallery shortcodes, image URLs and CSS references. Opaque custom serialization stays blocked.
- Supported sources: post content/excerpts, postmeta, options, termmeta, usermeta, comments and commentmeta; network metadata on Multisite.
- Protection for original images, intermediate sizes, edit backups and shared attachment files, including PDF preview images.
- Recursive raster-file enumeration, including AVIF; excludes symbolic links, legacy trash, cache and other sites’ upload directories.
- Fresh-scan authorization, file checksums, per-site file locks and recovery journals.
- Multi-checkpoint time-sliced AJAX requests and a resumable WP-CLI runner for long scans; only one worker may advance a scan at a time.
- Deduplicated reference index and indexed active-file reservations. Existing RC quarantine records remain protected through a legacy check.
- Atomic reservation of all attachment-family paths in a short InnoDB transaction; incompatible table engines block new operations.
- On single sites, successful attachment-metadata additions conservatively extend every active scan’s file-owner catalog under a shared database lock; unverified additions and reserved-path conflicts still invalidate scans.
- Changed uploads-directory offsets are re-enumerated with provisional file candidates discarded (up to five retries), rather than trusting a stale iterator offset.
- Private-vault status and the validated per-site storage path are visible to authorized administrators only; display never bypasses required authorization.
- Local attachment records and metadata survive quarantine. Original paths are never silently overwritten during recovery.
- Explicit permanent deletion requires a current complete scan and a typed confirmation. Nothing is purged on a schedule.
- Existing 1.0.0 trash records can be restored or explicitly migrated into private storage.
Database jobs read bounded batches. In the browser, several short checkpoints run per AJAX response. HTML post_content above the ordinary 2 MiB document limit is read in 65,536-character overlapping checkpoints (with a 64 MiB default overall HTML cap); a source checksum is verified before the record is marked complete. Large JSON, serialized structures and unsupported formats still stop the scan safely. A single slow database operation or file can still exceed a request’s budget. Persistent WP-CLI workers can keep a directory iterator open and avoid repeated seeking within the same command, but resuming after process exit still reopens the directory. This is not a promise of suitability for every shared host. Local file operations default to 64 MiB per file. Small reference documents default to 2 MiB, 5,000 references and 32 nesting levels. Unsupported sources stop the scan instead of silently authorizing deletion.
Privacy
The plugin sends no telemetry and makes no runtime requests to external services. Reference indexes can contain internal source identifiers and paths; expired scan indexes are removed in bounded cleanup batches on subsequent scan starts. Quarantine journals are retained for recovery and audit. Preview access requires an authenticated administrator and a nonce. WordPress’ own update and translation services are outside this plugin’s processing.
Installation
- Back up the database and uploads, then install on a staging copy.
- Upload the
gerdoo-orphan-media-cleanerdirectory into/wp-content/plugins/, or install the ZIP through WordPress. - Activate the plugin and open Tools -> Smart Media Cleaner.
- If prompted, complete the initial private-storage setup on the same screen. Check that the proposed private folder is not publicly served by any other domain/alias.
- Run a complete scan and manually review the candidates.
- Quarantine selected candidates, check the site, then run a fresh scan before any explicit permanent deletion.
For a separate read-only audit of a real unrestricted scan, go to “Quarantine and Recovery” and click “Scan the whole website” under the pre-deletion scan control. When every scan phase finishes, the plugin downloads gerdoo-omc-full-scan-YYYY-MM-DD.json automatically, containing index counts and explicit limitations. This does not quarantine or delete real files. The browser must remain open while the scan runs; a completed WP-CLI scan can also be loaded with its ID from the collapsed “Advanced server scan” panel. On a large media library this operation may take a long time. The report does not prove that any candidate is safe to remove.
For large libraries with WP-CLI and an administrator user ID, the scan can be advanced in the server process without keeping the browser open:
wp gerdoo-omc start --as-user=1 --seconds=300
The command prints a 32-character scan ID. Re-run it with resume, the same user ID and the scan ID until the phase is done:
wp gerdoo-omc resume SCAN_ID --as-user=1 --seconds=300
wp gerdoo-omc status SCAN_ID --as-user=1
To reclaim indexes belonging to expired scans in bounded batches without touching quarantined files, use:
wp gerdoo-omc cleanup --as-user=1 --seconds=300
Replace 1 with an authorized administrator’s numeric ID and SCAN_ID with the exact returned ID. The scan is not a cleanup command and never deletes files. In “Quarantine and Recovery”, expand “Advanced server scan”, enter the ID while signed in as that same administrator, then select “Show scan results” to review completed results. Schema upgrades invalidate prior scan IDs, and ordinary content/reference changes still invalidate the scan for safety. The lifetime is renewed on checkpoints (default seven days; filter gerdoo_omc_scan_lifetime, constrained to one through thirty days). Only standard attachment metadata additions on single sites are reconciled incrementally; this does not provide a fully transactionally consistent snapshot of an arbitrarily changing WordPress site. Plan a maintenance window for active publishing, uploads and unsupported integrations.
Private quarantine can now be configured through the initial setup panel in WordPress Tools without editing wp-config.php. The UI suggests a location only when it detects a conventional public-root boundary and its parent is writable; the administrator must verify that other virtual hosts or aliases cannot expose the folder. A location is created and validated only after the administrator explicitly clicks Save. The path is saved per site as the gerdoo_omc_vault_path option. The GERDOO_OMC_VAULT_PATH constant in wp-config.php remains supported and takes precedence over the option. The vault must be outside the document root, ABSPATH, WP_CONTENT_DIR and the uploads base directory. If this boundary or write access cannot be established, scans still work and quarantine is blocked. Changing the option is refused while active recovery records exist.
The WordPress database account must be able to create/alter plugin tables. The quarantine and reserved-paths tables must use InnoDB for crash-safe atomic reservations. New file operations are blocked if this cannot be verified.
Example on Linux: define( 'GERDOO_OMC_VAULT_PATH', '/home/example/private/gerdoo-media-vault' );
Example on Windows: define( 'GERDOO_OMC_VAULT_PATH', 'E:/WordPress-Private/gerdoo-media-vault' );
If using the optional constant, pre-create its parent directory and grant the PHP service account appropriate access. Use the same vault configuration for web requests and WP-CLI. Include the private vault in your backups.
Developer diagnostics and integration fixtures are not included in this plugin package. They have no public admin screen or callable AJAX endpoint.
FAQ
Is every candidate safe to remove?
No. References in arbitrary custom tables, theme/plugin source files, dynamic PHP, remote consumers or a CDN with an unrelated path scheme cannot be exhaustively proven absent. Ambiguous numeric/basename evidence conservatively retains possible matches. Direct SQL edits can bypass WordPress change hooks. Do not edit/import content concurrently with a scan or deletion. Offloaded, unmapped or incomplete attachment families are not eligible for file changes; an unindexable family can stop the scan.
What happens when a request fails?
An incomplete scan cannot authorize file changes. A quarantine operation has a durable private manifest before any source removal. Open the trash tab to continue or restore an interrupted operation. Conflicting destinations, changed checksums and changed references stop operations rather than overwriting data. A failed copy can leave a partial private payload; restore the retained source and inspect the journal before retrying. Permanent deletion is irreversible once it starts.
Is version 1.0.0 trash automatically made private?
No. Its table and files are preserved exactly during upgrade. Use the explicit private migration action. Until that succeeds, the old uploads/gerdoo-trash-bin location remains public. Old records that are corrupt or not raster images require manual recovery.
Does this support Multisite?
Tables, scans, upload boundaries and vault directories are per blog. Each blog upgrades lazily on admin access, including blogs created after network activation. References across blogs, network metadata and shared user metadata are scanned conservatively, with a shared invalidation token. The default maximum is 1,000 sites; larger installations stop safely unless trusted code adjusts gerdoo_omc_max_sites. Network-wide content/file mutations outside standard WordPress hooks still require operator coordination.
Can other plugins extend detection?
Yes. Trusted code may use gerdoo_omc_reference_sources, gerdoo_omc_attachment_files, and gerdoo_omc_excluded_directories. Source definitions are developer configuration, not user input. Limits can be adjusted with gerdoo_omc_max_document_bytes, gerdoo_omc_max_document_references, gerdoo_omc_max_large_html_bytes and gerdoo_omc_max_file_bytes. Increasing limits may exceed hosting resources. Do not remove necessary exclusions without understanding their ownership boundaries.
What happens on uninstall?
Recoverable files, attachment quarantine markers, legacy data, operation journals and database recovery tables are deliberately retained. Reinstall with the same uploads/vault locations to regain access. Restore or permanently delete active quarantine entries before any manual cleanup. Only then may an administrator remove the plugin’s gerdoo_omc_* tables/options, the old gerdoo_media_trash table if empty, and the empty vault. Do not remove quarantine markers while their files are still missing.
Screenshots
Changelog
1.1.0
- Introduce reversible, private file quarantine with recovery journals, checksums, collision protection and manual approval before removal.
- Preserve legacy 1.0.0 trash records on upgrade; add explicit migration into private storage and recovery of old files.
- Scan registered media and uploads independently with bounded, resumable reference indexing; provide a combined audit for deletion authorization and WP-CLI commands.
- Protect image families, generated sizes and shared files; reconcile standard attachment metadata updates during WooCommerce image regeneration and handle Unicode filenames safely.
- Add thumbnails in candidate and quarantine lists, numbered-page navigation, clearer status messages and safer error handling.
- Require a current complete combined scan and explicit confirmation before irreversible deletion. No automatic purging.
1.0.0
- Initial release with database scanner, host scanner and physical trash.



