=== Hook Inspector ===
Contributors: aiwpcoder
Tags: debug, developer, hooks, actions, filters, profiling
Requires at least: 6.0
Tested up to: 6.7
Requires PHP: 7.4
Stable tag: 1.0.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Capture, visualise, and debug every WordPress action and filter fired on the current request.

== Description ==

Hook Inspector surfaces the entire hook graph for the current request with enough detail to actually debug it.

**Core Features**

* **Request Timeline** - Every do_action and apply_filters call captured with hook name, priority, callback identifier, arguments, execution time, and peak memory delta.
* **Hook Tree** - A nested view showing parent and child relationships where hooks fire inside other hooks.
* **Search and Filter** - By hook name, callback, originating plugin or theme, priority, minimum duration, or "only filters". Saved filter presets per user.
* **Callback Toggle** - Temporarily disable any specific callback on any hook, for the current user's session only, via a nonce-guarded AJAX action. Never persists to other users.
* **Diff Mode** - Compare two page loads side by side to see which hooks appeared or disappeared.
* **Export** - One-click export of the captured trace as JSON for bug reports and support tickets.
* **Admin Bar Counter** - Live count of hooks fired on the last request with a drop-down menu.
* **Per-User Enable Switch** - Instrumentation only runs when a permitted admin has the debug toggle on.

**Technical Approach**

Registers a universal listener via the 'all' meta-hook, recording traces to a per-request in-memory ring buffer (configurable cap, default 1000). Persists on shutdown to a transient keyed by user and request ID. Arguments are JSON-safely serialised with depth and size limits. Timing via hrtime() for microsecond accuracy.

**Security**

* manage_options capability gate
* Nonce verified on every AJAX action
* All output escaped with WordPress escaping functions
* All input sanitised
* Disabled entirely for logged-out users
* Off by default unless WP_DEBUG is true or admin explicitly activates it

== Installation ==

1. Upload the `hook-inspector` folder to the `/wp-content/plugins/` directory.
2. Activate the plugin through the 'Plugins' menu in WordPress.
3. Navigate to Tools > Hook Inspector.
4. Click 'Enable Tracing', then reload any page to capture hooks.

== Frequently Asked Questions ==

= Does this affect site performance for visitors? =

No. Tracing only runs for logged-in admins who have explicitly enabled it via their per-user toggle. There is zero overhead for visitors or non-debug admins.

= Is it safe to use on a staging site? =

Yes. Callback toggling only affects the current user's session and never touches output for any other user.

= How long are traces retained? =

Traces are stored as WordPress transients and expire after 1 hour.

= What is the ring buffer cap? =

By default the last 1000 hooks fired are captured. Earlier hooks are dropped when the buffer is full.

== Screenshots ==

1. Timeline view showing all hooks fired on the current request.
2. Hook tree showing nested relationships.
3. Diff mode comparing two request traces.
4. Admin bar counter and dropdown.

== Changelog ==

= 1.0.0 =
* Initial release.
* Request timeline with timing and memory data.
* Nested hook tree view.
* Search and filter with saved presets.
* Per-session callback toggle.
* Diff mode for before/after comparison.
* JSON export.
* Admin bar drop-down counter.

== Upgrade Notice ==

= 1.0.0 =
Initial release.
