Media Audit Pro™ Developer API
Media Audit Tool™ is extensible. If you maintain a Joomla extension that stores, references or generates media files, you can teach Media Audit Tool about it — so your users get accurate results instead of false positives.
Everything here is a plain Joomla plugin event. There is no SDK to install, no registration, and no key to request.
Before you write any code
Most people don't need this page.
Media Audit Pro™ includes a no-code Analyzer Builder. Point it at a database table, tell it which column holds the image path, and it starts reporting — then export it as a real installable plugin. If your extension keeps its media paths in a table column, that is the faster route and it survives updates.
Write a plugin when the Builder can't reach what you need: paths assembled at runtime, serialised or nested data, references spread across several tables, or anything requiring logic to resolve.
The governing principle
One idea explains every decision in the API:
Analyzers provide facts. The Engine provides intelligence.
Analyzers answer "Where?" The Asset Intelligence Engine™ answers "So what?"
Your analyzer reports what it observes — this object references this path. It does not normalise paths, deduplicate, decide whether an asset is really orphaned, judge renderability, or generate recommendations. All of that belongs to the Engine.
This is not a stylistic preference. It is what keeps your plugin small, keeps it working when our analysis improves, and means you never have to ship an update because we changed how reports are generated.
If a feature can be implemented in the Engine, it does not belong in an analyzer.
How the pieces fit
- Media Audit Tool™ owns the inventory — scanning, the asset database, Trash with Safe Restore, the Dashboard and Inspector
- Analyzer plugins (
plg_mat_*) each understand one extension's data structures and report references found in them - Asset Intelligence Engine™ consumes those facts and produces correlation, renderability, optimization analysis and the Asset Intelligence Report
You write the middle layer. We handle the rest.
The three contracts
These are separate, sibling contracts covering different concerns. Implement whichever apply — they are independent, and most extensions need only one.
| Contract | Answers | Event |
|---|---|---|
| Analyzer Facts v1.1 | Where are assets referenced? | onMediaaudittoolCollectReferences() |
| Inventory Hints v1.0 | Which files are mine and must not be trashed? | onMediaaudittoolCollectInventoryHints() |
| Cache Locations v1.0 | Where does my extension write derivative files? | onMediaaudittoolCollectCacheLocations() |
Analyzer Fact Contract
Return an array of fact records describing where your extension references media. Each record carries the owning object, its publication state, an optional public URL, and one or more candidate paths — you supply what you observed, the Engine resolves it against the inventory.
Implement this if your extension stores references to user media.
Inventory Hints Contract
Some extensions ship their own interface graphics — category icons, badges, file-type icon sets — inside /images/<extension>/ rather than /media/com_<extension>/. Because they are loaded by filename convention rather than referenced from a database field, no analyzer can produce facts for them. Without a hint they surface as orphans, sometimes by the hundreds, and an administrator can end up trashing your extension's own working files.
Implement this if your extension keeps bundled graphics outside /media/. It takes about ten minutes and prevents your users blaming you for a broken interface.
Cache Locations Contract
The recommended workflow after trashing unreferenced assets is a front-end visual check before purging anything permanently. That check is worthless if the front end is still serving stale cached copies.
Media Audit Tool already knows Joomla's file-based system cache and finds conventionally-named folders heuristically — images/thumbs, images/cache, images/resized and similar. It cannot guess at something like YOOtheme Pro's template cache, which lives outside /images entirely and follows no convention we could infer.
Implement this if your extension writes generated or derivative image files anywhere non-obvious.
Stability
All three contracts are stable. Additions are always optional: an existing analyzer keeps working, unchanged, when a contract gains a field. Breaking changes would arrive as a new contract rather than as a revision to an existing one — Inventory Hints and Cache Locations were both introduced after the Fact Contract, and neither altered it.
The legacy onMatCollectReferences() alias is retained for compatibility.
Questions
Analyzer development questions are welcome in the support area, whether or not you hold a licence. If you have built an analyzer for an extension we don't cover, we would like to hear about it.