=== Bloat Detector – Find Unused Add-ons, Clean Leftover Data & Speed Up Your Site ===
Contributors: dotance
Tags: unused plugins, plugin cleanup, plugin manager, cleanup, performance
Requires at least: 5.9
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 1.0.1
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Finds the active plugins your site never uses: tracks shortcodes, blocks, widgets, assets and admin screens, and shows what is safe to remove.

== Description ==

Sites collect plugins. Thirty, forty, sixty active ones, and nobody remembers what half of them are for. The Plugins screen tells you which are *inactive*; it says nothing about which *active* plugins never do anything.

Bloat Detector answers that question with evidence instead of guesswork. It observes what each active plugin actually does – on the front end, in wp-admin, in the background – for a window of time, adds a static scan of your content that gives results immediately, and puts an honest verdict on every plugin under **Plugins → Usage Report**.

**What counts as "used"**

* A shortcode, block, Elementor widget or sidebar widget of the plugin rendered on a page
* One of its scripts or styles was printed on the front end
* One of its REST routes or public AJAX actions was called
* One of its admin screens was opened, or an admin AJAX action ran
* Its shortcode, block or Elementor widget appears in published content (found by the daily scan, so this works on day one)

**The four verdicts**

* **In use** – something visitors see or request ran inside the window.
* **Admin tool** – nothing on the front end, but you open its screens. Shown with how often and when.
* **Background** – no measurable activity, but the plugin hooks into mail, login, comments, cron, rewrite rules, WooCommerce payment or shipping, or similar passive points. The report says which hooks and asks you to check manually. It is never called unused.
* **No activity** – nothing at all, with a confidence that grows with the days observed: low under a week, medium up to a month, high from 30 days.

**Footprint and load cost**

Each plugin shows its folder size, the options it likely stores (with how much of that is autoloaded on every request) and any custom tables, so you can see what removing it would give back. The report header adds it up for the "no activity" plugins. Each plugin also shows what it costs to load – the milliseconds and memory its main file takes on every request, averaged over real page loads, and how many hook callbacks it registers – so you can see which plugins are slow as well as which are unused.

**Cleanup of what deleted plugins left behind**

The Cleanup tab lists option groups and database tables that no installed plugin, the active theme or WordPress itself accounts for – the usual leftovers of plugins deleted long ago – with their size and example names. Delete a group or drop a table after typing its name to confirm. The matching is a heuristic and the screen says so; look before you delete.

**Trial deactivation – the safe way to remove a plugin**

Instead of deleting on a hunch, switch the plugin off for a trial period (7 days by default). A notice in wp-admin lists every plugin on trial with three buttons: **Delete**, **Keep off**, **Reactivate**. If nobody decides before the trial ends, the plugin is reactivated automatically and the report says so. Security, backup, cache and redirect plugins are never offered a trial; you can add your own to the protected list.

**Designed to stay out of the way**

* One database write per request, on shutdown, for the whole request – never one per hit.
* Front-end recording can be sampled (1 in 5, 1 in 10 …) on busy sites. Admin, AJAX and REST requests are always recorded.
* The daily content scan runs in batches on large sites.
* The usage table is bounded: one row per distinct signal, pruned at twice the window.
* Only administrators (`manage_options`) can see the report. Deactivating needs `activate_plugins`; deleting needs `delete_plugins`. Every action is nonced.

**Also on the Plugins screen**

A "Usage" column shows each plugin's verdict and when it was last seen, right in the list you already use.

**For developers**

* `bloat_detector_protected_plugins` – filter the array of plugin folder names that are never offered a trial deactivation.
* `bloat_detector_option_owners` – filter the `prefix => plugin slug` map the Cleanup tab uses, so your plugin's options are never listed as unclaimed.

To measure every plugin's load cost the plugin keeps itself first in the `active_plugins` list (the same technique the Freemius SDK uses). Nothing else about load order changes.

Not in this version: multisite network reports, theme usage, WP-CLI commands. See the changelog for what is planned.

== Installation ==

1. Upload the `bloat-detector` folder to `/wp-content/plugins/`, or install it from the Plugins screen.
2. Activate it. The usage table is created and observation starts.
3. Go to **Plugins → Usage Report**. Click **Scan now** for immediate static results; runtime verdicts become reliable after 7 days.

== Frequently Asked Questions ==

= Does it slow the site down? =

No measurable amount. Each hook does a lookup in a cached name-to-plugin map and adds one entry to an in-memory list; the list is written once, on shutdown, in a single statement. On very busy sites you can sample front-end page views under Settings.

= Why does a plugin I use show "No activity"? =

Because nothing it does was observed inside the window. Two common reasons: the observation has only just started (check the days observed in the header), or the plugin's work happens somewhere the observer cannot see – a custom template that calls its PHP functions directly, for example. A "no activity" verdict is a reason to try a trial deactivation, not proof. That is what the trial is for.

= What does "Background" mean? =

The plugin has callbacks on hooks that fire without rendering anything – outgoing mail, login, comment handling, scheduled tasks, rewrite rules, WooCommerce payment or shipping. Those cannot be measured by watching page views, so the report tells you which hooks it found and leaves the decision to you.

= What happens if I forget about a trial? =

The plugin is reactivated automatically when the trial ends, and its card shows "auto-reactivated – you did not confirm". Nothing is ever deleted without you clicking Delete.

= Which plugins are protected? =

Wordfence, Sucuri, All In One WP Security, UpdraftPlus, Sitecarry, Settings Undo, LiteSpeed Cache, WP Rocket and Redirection, plus anything you add under Settings and anything returned by the `bloat_detector_protected_plugins` filter. Protected plugins still get a verdict; they just do not get a trial button.

= Is the footprint exact? =

The folder size and file count are. Options and tables are matched by name prefix from the plugin's folder name, which is a heuristic – it is labelled "approx." for that reason.

= How is load cost measured? =

WordPress fires an action after each plugin file is included. The plugin records the time and memory between two of those, attributes it to the plugin that was just loaded, and keeps a moving average across real requests (persisted on one request in ten). Plugins loaded before this one cannot be measured, which is why it keeps itself first in the load order. Hook counts come from the daily scan.

= Is the Cleanup tab safe? =

It only lists things whose name prefix matches no installed plugin, no active theme and nothing in WordPress core or its known-prefix list. That is a heuristic, so read the example names first, take a backup, and prefer deleting option groups (which Settings Undo records, if you have it) over dropping tables, which cannot be undone.

= Where is the data stored? =

In one table, `{prefix}bloatd_usage`, plus a handful of options prefixed `bloatd_` (settings, the name map, trials, load-cost averages). Uninstalling the plugin leaves them in place unless "delete data on uninstall" is enabled under Settings.

== Screenshots ==

1. The report: header facts, verdict tabs, one card per plugin with verdict, signals and footprint.
2. A "no activity" card with Details open: every recorded signal with hits, first and last seen.
3. The Cleanup tab: option groups and tables no installed plugin claims, with typed confirmation before deleting.
4. The trial notice: Delete, Keep off or Reactivate for each plugin on trial.
5. The "Usage" column on the Plugins screen.
6. Settings: window, sample rate, trial length, protected plugins, uninstall, reset.

== Changelog ==

= 1.0.1 =
* New animated Bloat Detector icon beside the page title.

= 1.0.0 =
* First release: runtime observation of shortcodes, blocks, Elementor widgets, sidebar widgets, front-end and admin assets, REST routes, AJAX actions and admin screens; daily static scan of published content and Elementor data; passive-hook and cron detection; four verdicts with confidence; per-plugin footprint (size, options, autoloaded bytes, tables); trial deactivation with auto-reactivate; "Usage" column on the Plugins screen; per-plugin load cost (milliseconds, memory, hook count); Cleanup tab for unclaimed options and tables left by deleted plugins; sampling, protected list and reset under Settings.

== Upgrade Notice ==

= 1.0.0 =
First release.
