WP Query Sentinel

Real-time N+1 query and slow-query detection for WordPress, surfaced directly in the admin bar.

The Problem

A WordPress page that queries 10 posts and then loops through them to fetch each author's name doesn't make 1 query — it makes 11. Scale that to a category archive with 100 posts and it's 101 queries per page load, invisible until the site is under real traffic and the database starts choking. Existing tools like Query Monitor are excellent but general-purpose profilers; there's no lightweight, zero-config tool that specifically watches for the repeated-pattern signature of an N+1 loop and flags it before it ships to production.

The Solution

WP Query Sentinel hooks into every SQL statement WordPress executes via the query filter, normalizes each query into a signature (stripping literal values, IDs, and IN-list contents so that structurally identical queries collapse together), and counts occurrences per request. Any signature repeated past a configurable threshold is flagged as a likely N+1 pattern and logged to a report screen under Tools → Query Sentinel — with a live query count visible in the admin bar on every page load.

[Every SQL query] --> [Normalize to signature] --> [Group + count per request]
                                                            |
                                                  count >= threshold?
                                                            |
                                                     [Flag + log report]

Technical Highlights

• Zero dependencies, zero external services. Pure PHP hooked into WordPress core filters — works on any host, including free-tier shared hosting with no ability to install anything beyond the plugin itself.
• Query normalization via regex signature matching — collapses WHERE post_id = 12 and WHERE post_id = 87 into the same pattern, which is the actual mechanism that makes N+1 loops detectable programmatically rather than by eyeballing a query log.
• Security-first admin interactions — every state-changing request goes through check_admin_referer() and a current_user_can( 'manage_options' ) capability check, including the settings form.
• OOP, PSR-12-formatted, namespaced — no procedural spaghetti; a small autoloader avoids requiring Composer on shared hosting while keeping the codebase organized like a real application.
• Unit tested — the core normalization logic (the part that actually decides whether two queries "match") is covered by PHPUnit tests using WordPress's official test scaffolding, not just manually verified.
• Rolling report log, not a live dashboard hack — flagged patterns are persisted via update_option() and capped at the last 20 flagged requests, so the report survives across page loads without unbounded database growth.

Installation

1. Clone or download this repo into wp-content/plugins/wp-query-sentinel
2. Activate via Plugins in wp-admin
3. Browse your site's front end — flagged patterns will appear under Tools → Query Sentinel

Running tests

composer install
composer test   # runs PHPUnit against WordPress's test scaffolding
composer lint    # runs PHP_CodeSniffer against PSR-12 + WordPress security rules

Roadmap

• [ ] Query timing (requires SAVEQUERIES) surfaced per flagged pattern, not just count
• [ ] Slack/email digest of flagged patterns on a schedule
• [ ] WP-CLI command for running analysis against a scripted crawl of key pages