manifest / media / wpusedmedia

Used Media Pro

A more powerful WordPress media manager: see where every library item is used, import & re-attach external images, and safely clean up unused media.

by 397 Digital · github.com/ezsmith397/wpusedmedia · website

★ 0stars

Install

Download source zip No release zip yet

This is the repository archive. It installs, but the folder name will carry the branch suffix and updates will not flow.

Install straight from GitHub with WP-CLI:

wp plugin install https://github.com/ezsmith397/wpusedmedia/archive/refs/heads/main.zip

No built-in updater. New versions won't appear under Dashboard → Updates. Install new releases yourself, or let Git Updater track the repository.

Readme github.com/ezsmith397/wpusedmedia ↗

A more powerful media manager for WordPress. It adds a Media → Used Media screen that shows where every library item is actually used, and (as it grows) will find external images, download and re-attach them locally, and safely clean up unused media.

Status: early development. Phase 0–1 is implemented (usage index + enhanced library view). External-image import and cleanup tools are on the roadmap below.

Why

Native upload.php shows your media, but it can't tell you which post, page, or builder layout references a given file — so you can never safely delete anything. Used Media Pro builds a usage index across your content and answers that question.

Architecture

Everything hangs off one extensible contract, Source_Adapter (includes/interface-source-adapter.php). Each place media can be referenced is a pluggable adapter:

scan_references() — feeds the usage index (where is this attachment used?)
scan_external() — finds off-site image URLs (Phase 4)
replace() — swaps an external URL for a locally imported attachment, re-attaching the id (Phase 4)

The golden rule: every read/write of a reference goes through an adapter — never a global find/replace, which corrupts serialized/JSON builder data.

Third parties (and future modules) register adapters via the ump_source_adapters filter.

Shipping adapters

Adapter	Status	Covers
`core_content`	✅ Phase 1	classic + block editor content, featured images, reusable blocks, FSE templates
`bricks`	✅ Phase 2	Bricks Builder layout data (`_bricks_page_content_*` postmeta) — image elements, backgrounds, logos, galleries

Roadmap

Phase	Deliverable
0	Scaffold, menu, settings, adapter registry ✅
1	Core adapter + usage index + enhanced list view with "Used in" ✅
2	Bricks adapter feeding the same index ✅
3	"No references found" cleanup + trash-and-restore delete + multi-select bulk delete ✅
4	External image scan + download & full re-attach + undo (+ broken-image health check, where-used, broken CSV report, bulk import) ✅
5	Incremental index on `save_post` / delete, polish ✅

Design decisions locked in: distributable build with a trusted-domain allowlist, trash-and-restore deletes (nothing hard-deleted until you purge), and full re-attach on external-image replacement.

Install (development)

Clone into wp-content/plugins/ and activate:

git clone https://github.com/ezsmith397/wpusedmedia.git wp-content/plugins/used-media-pro

Then go to Media → Used Media and click Build index.

Development

Coding standards are enforced with WordPress Coding Standards via PHP_CodeSniffer:

composer install     # install dev tooling (PHPCS + WPCS)
composer lint        # check against the WordPress standard (phpcs.xml.dist)
composer lint:fix    # auto-fix what can be fixed (phpcbf)

The ruleset lives in phpcs.xml.dist (prefix umedia / UsedMediaPro, text domain used-media-pro, PHP 7.4+, WP 6.0+).

Requirements

WordPress 6.0+
PHP 7.4+

License

GPL-2.0-or-later. See LICENSE.