WordPress Performance Toolkit

A production-style WordPress plugin for administrator-authorised performance captures. It helps developers diagnose slow database queries, duplicate SQL, oversized autoloaded options, slow hook callbacks, large scripts and styles, PHP memory pressure, caching gaps, and server-side page-generation time.

Why this project matters

Performance incidents rarely come from one metric. A slow request may combine repeated database reads, a large autoload payload, synchronous callbacks, unnecessary assets, missing caches, and high memory usage. This plugin stores those signals in one redacted report and turns threshold breaches into practical recommendations.

Features

• Short-lived, same-site capture URLs bound to the administrator who created them.
• Query count on every capture and detailed timing when the capture enables SAVEQUERIES.
• SQL literal redaction, normalized fingerprints, slow-query ranking, and duplicate-query aggregation.
• Autoload payload totals plus the largest autoloaded option names and sizes.
• Experimental per-callback timing for a deliberately limited set of common hooks.
• JavaScript and CSS size analysis for locally enqueued files, including inline data.
• PHP current/peak memory, memory limit, WordPress/PHP versions, OPcache, WP_CACHE, and persistent object-cache signals.
• Server-side page-generation time measured from WordPress request start to shutdown.
• Severity-ranked caching, database, hook, asset, and runtime recommendations.
• Private report history in a custom WordPress table.
• JSON and CSV exports protected by capabilities and nonces.
• Configurable thresholds and report retention.
• Optional uninstall cleanup.
• PHPUnit tests, PHP syntax checks, GitHub Actions, Docker Compose, and release packaging.

Requirements

• WordPress 6.5+
• PHP 8.1+
• An administrator account, or a role granted the capability returned by wptk_required_capability

Installation

WordPress dashboard

1. Build or download wordpress-performance-toolkit-plugin.zip.
2. Open Plugins → Add New → Upload Plugin.
3. Activate the plugin.
4. Open Tools → Performance Toolkit.

Development

git clone https://github.com/emmanuel0635/wordpress-performance-toolkit.git
cd wordpress-performance-toolkit
composer install
docker compose up -d

WordPress will be available at http://localhost:8080. Complete the installation screen and activate the mounted plugin.

Capture workflow

1. Open Tools → Performance Toolkit.
2. Enter a URL on the same WordPress site.
3. Optionally enable deep callback profiling.
4. Select Start capture.
5. Browse the captured page normally.
6. Return to Tools → Performance Toolkit → Reports.
7. Review or export the saved report.

The token expires after ten minutes and is deleted after a successful capture. Detailed query logging is enabled only for that request. Reports are never exposed through a public REST endpoint.

Report model

summary
├── page generation, queries, memory, autoload and asset counts
queries
├── slow queries (redacted)
└── duplicate normalized query groups
autoloaded_options
├── total bytes and count
└── large option names and sizes
hooks
├── callback totals
└── slow callbacks and source origin
assets
├── scripts
└── styles
environment
└── cache/runtime configuration
recommendations
└── severity, category, title and remediation detail

Security and production safety

• Every screen and action checks a capability; the default is manage_options.
• Settings, delete, capture, and export requests use WordPress nonces.
• Capture targets must use the site's exact scheme, host, and effective port.
• Capture tokens use 128 bits of randomness, expire after ten minutes, and are bound to a user ID.
• SQL string, numeric, hexadecimal, and quoted literals are redacted before storage.
• Report exports remain administrator-only.
• Deep callback profiling is opt-in because wrapping third-party callbacks changes the execution path.
• SAVEQUERIES adds overhead and should not be enabled globally on production traffic.

See SECURITY.md and docs/ARCHITECTURE.md.

Hook-profiling limitations

WordPress does not expose a public API for timing each registered callback. The optional deep mode therefore wraps callbacks already registered on selected non-reference hooks. It intentionally excludes unknown and reference-sensitive hooks, may miss callbacks registered after instrumentation, and should be used only for a targeted diagnostic request. The report states these limitations rather than presenting the numbers as a complete trace.

Before-and-after measurements

The repository includes an actual synthetic microbenchmark, generated by php scripts/benchmark.php on PHP 8.4.16. It validates the recommendation logic around caching repeated analysis and duplicate work; it is not presented as a real-site WordPress benchmark.

See docs/BENCHMARKS.md for methodology and a real-site measurement checklist.

Commands

composer validate --strict
composer lint:php
composer test
composer benchmark
bash scripts/build-zip.sh

Architecture

• Request_Context validates a temporary capture session and enables query logging early.
• Runtime_Collector coordinates analyzers and stores one report at shutdown.
• Analyzer classes have narrow responsibilities for queries, options, hooks, assets, and environment data.
• Recommendation_Engine is a pure rules component and can be unit tested without WordPress.
• Report_Repository owns schema installation, persistence, retention, and retrieval.
• Admin_Page owns capabilities, nonces, navigation, capture creation, rendering, and exports.

Extensibility

add_filter('wptk_required_capability', static function (): string {
    return 'manage_network_options';
});

The next production extension would add custom analyzer and recommendation filters, multisite network aggregation, WP-CLI capture commands, and secure comparison views between two reports.

License

GPL-2.0-or-later.