Find expensive functions, repeated work and costly call paths in one WordPress plugin using Xdebug in an isolated WordPress Playground site. Keep raw Cachegrind files for KCachegrind/QCachegrind, or inspect the generated offline HTML viewer, function/edge CSV and complete JSON. Node built-ins power the engine; it uses the already installed wp-plugin-regression launcher and an existing matching Playground Xdebug artifact.
Playground diagnostics do not predict production performance.
In your open plugin repository, tell your AI agent:
Implement https://github.com/theseoframework/wp-plugin-performance for this repo.- Download or copy this repository's files into a private folder outside your plugin source.
- Prepare the existing Node, wp-plugin-regression and Xdebug dependencies listed under Requirements and configuration. This engine itself needs no
npm install. - Copy
skills/playground-performance/into your plugin's.cursor/skills/playground-performance/and configure the private engine locations as described below. - Open a terminal in the engine folder and run
node run.js --help. Follow Capture profiles when ready to profile.
Before an agent acquires missing dependencies or launches WordPress, obtain the user's decision and follow the recorded permission workflow below.
Playground diagnostics do not predict production performance. PHP-WASM, SQLite translation, filesystem behavior and profiling overhead can change both absolute timings and the relative cost of operations. Use profiles to identify candidate improvements, then confirm useful gains on representative native WordPress hosting with profiling disabled.
Inclusive times overlap: do not add parent and child costs. Xdebug can amplify frequent function calls disproportionately. A large profiled saving does not establish an equivalent normal-request improvement. Calls count profiler entries; recursive calls and generator resumptions need interpretation. This tool does not establish which plugin is fastest or publish competitor rankings.
- Node 20.18 or newer for offline inspection and tests. Live profiling additionally requires a JSPI-capable Node runtime for the extension-manifest workflow; unsupported runtimes fail before launching WordPress.
- An already installed compatible wp-plugin-regression declaring
wpPluginPerformanceApi: 1, with per-site OPcache profiles and the--clioverride. - A Playground PHP build exposing
getXdebugExtensionPath()and its existing, matching Xdebug artifact. The initial workflow was exercised with PHP 8.3; other branches must actually provide their extension. No branch silently falls back to another version or unprofiled timing. - A materialized local plugin directory with a valid Version header.
No command installs tools, invokes Git or modifies the plugin source. The launcher may need WordPress/runtime files; prepare these beforehand when working offline. Missing software should be installed explicitly by the operator.
Copy skills/playground-performance/ into the consumer's
.cursor/skills/playground-performance/. Keep runtime implementations here.
See editor integration.
Store the existing engine locations privately in the consumer:
{
"directory": "../wp-plugin-performance",
"regressionDirectory": "../wp-plugin-regression"
}Save that JSON as .local/playground/performance/engine.json.
Before live use, obtain the user's decision and record exactly PLAYGROUND=True
or PLAYGROUND=False in .local/playground/permission.txt. Never invent consent,
copy another consumer's permission, or create the flag during installation.
Offline inspection does not require live consent.
Copy examples/profile.json into the consumer's private
workspace. Set the actual plugin slug, main PHP file, path and explicit installed
WordPress/PHP versions. The example versions are reproducible inputs, not a claim
about the latest releases. Optional options supplies deliberate local WordPress
options; optional xdebugArtifact selects an existing matching extension file.
node run.js doctor --root ../my-plugin --regression-dir ../wp-plugin-regression
node run.js profile --root ../my-plugin --config .local/profiling/plan.json --regression-dir ../wp-plugin-regression
From an installed consumer skill:
node .cursor/skills/playground-performance/scripts/performance.js profile --config .local/profiling/plan.json
The default example captures five routes: blog homepage, static homepage,
posts page, post and page. Three unprofiled warmups and one triggered capture
per route produce 20 page requests and five raw files, plus setup/control
requests. For a closer look at selected routes, use
--profiles=3 --scenarios=home-static,post.
Each capture remains separate; routes and repeated samples are never pooled into
a product score. Other supported GET scenarios include category, tag, search,
404, dashboard, posts-list, pages-list, post-editor and page-editor. Unsupported
routes and editor-save are rejected before captures.
The command creates an owned disposable site, seeds identical local content, activates only the selected plugin, blocks outbound WordPress HTTP/mail, and uses real WordPress authentication for admin requests. It validates fresh execution tokens, user state, native route, status, body and trigger state. Source fingerprints, actual runtime and request evidence are retained. PHP/SQL diagnostics, changed activation/source, missing Xdebug and incomplete profiles fail the run. WordPress receives an independent copy of the selected plugin mounts, never writable working-tree files. Both original and executed PHP fingerprints must remain unchanged. Snapshots and evidence stay under the private run directory. Only that owned session is stopped, including on failure; unrelated sessions are never stopped. Site data remains disposable launcher state. Do not run this MU instrumentation on production sites.
Open the generated report.html. Filter plugin functions or inspect WordPress
and internal callees; sort by self time, inclusive time or call count. Select a
function for its direct caller/callee edges. Raw raw/cachegrind.* files work
in KCachegrind/QCachegrind without the custom viewer.
Build a fresh report from a validated saved run, without starting WordPress:
node run.js hotspots --root ../my-plugin --input .local/profiling/saved-run --output .local/profiling/review
Or inspect an existing uncompressed Xdebug Cachegrind file:
node run.js hotspots --root ../my-plugin --input .local/profiling/cachegrind.out --output .local/profiling/review --plugin-prefix /wordpress/wp-content/plugins/my-plugin
A standalone import has no request/source validation provenance; the report
labels that limitation. Raw profiles may contain private paths and function names:
keep consumer evidence private. Reports use no CDN, telemetry or remote assets.
Saved-run imports retain recorded runtime, plugin/source hashes, request identity
and the original manifest hash in HTML, Markdown, JSON and provenance.json.
Missing historical fields are explicitly unknown; a standalone file cannot
establish its hosting environment from its header alone.
Ask whether to keep raw Cachegrind files or prune them after the saved report
is verified. With the user's choice, set "rawRetention": "prune" or
"rawRetention": "keep" in the consumer's private
.local/playground/performance/engine.json. Use
--raw-retention=prune or --raw-retention=keep to override it for one capture
run. When unset, raw files stay available for a later decision.
Automatic pruning runs after the site has stopped and the completed report has been written. For an older run, preview the file count and bytes first:
node run.js prune --root ../my-plugin --input .local/profiling/saved-run
node run.js prune --root ../my-plugin --input .local/profiling/saved-run --apply
Pruning verifies the report, manifest and raw hashes. It removes only the raw
files named in that run's manifest and records them in raw-prune.json.
Cleanup skips runs marked keep, incomplete runs and runs with missing evidence.
The saved HTML, JSON, CSVs and provenance remain usable after pruning. Keep raw
files when you need KCachegrind, a fresh parse or evidence for an investigation.
Older analysis scripts may have left separate cachegrind.*.json files.
Use Python 3 and the helper below to preview one exact cache directory, then
consolidate those files into parsed-cache.zip. It verifies each member's
SHA-256 before removing loose files. Restore before running a historical
script that reads those files by name.
python tools/parsed-cache.py pack --input path/to/parsed-profiles
python tools/parsed-cache.py pack --input path/to/parsed-profiles --apply
python tools/parsed-cache.py restore --input path/to/parsed-profiles --apply
Use a profile as a hypothesis. Preserve output, filters and observable behavior;
reduce actual work, then measure without profiling. Optional same-plugin
before/after timing remains available through run, prepare, resume,
stop, report and export. Plans, saved reports and exports require explicit
identities with one shared plugin slug and main file. Cross-plugin data,
additional activated plugins, unknown identities and legacy ranked summaries
are rejected. Ranks are not computed or exported. Rebuild older same-plugin
reports from their raw checkpoints with explicit identity metadata.
See before/after instructions,
measurement scope and runtimes.
Cross-runtime timing conversion and production leaderboards are unsupported.
npm test
node run.js --help
node test/profile-runtime.js ../wp-plugin-regression 8.3
node test/profile-guard.js <installed-php> <wordpress-source>
Synthetic tests check the parser, reports, request validation, consent, source identity and lifecycle failures. They are not evidence of a real-world speedup. See release checks. License: GPL-3.0-only.