WP Doctor

WP Doctor is a production-oriented WordPress diagnostics and reliability plugin. It helps administrators answer four questions with evidence: what is slow, what is broken, what changed, and why it happened.

The current 0.1.0 release is an intentionally bounded foundation. It includes secure administration and REST surfaces, a light/standard diagnosis engine, health scoring with explanations, a compact change timeline, fatal-error capture, secret redaction, report export, retention jobs, WP-CLI commands, and an optional MU rescue agent. Deep request attribution, controlled conflict isolation, update rollback, browser monitoring, and third-party adapters remain explicitly deferred; see Implementation Status and Known Limitations.

Requirements

• WordPress 6.6 or newer
• PHP 8.1 or newer
• MySQL 5.7 / MariaDB 10.4 or newer
• Node.js 20+ only for JavaScript tests
• Composer 2.7+ for development tools and optimized release autoloading

Install

For development, clone the repository into wp-content/plugins/wp-doctor, then run:

composer install
npm install
wp plugin activate wp-doctor

For production, install the ZIP created by npm run package through Plugins > Add New > Upload Plugin.

WP Doctor creates dedicated, non-autoloaded diagnostic tables during activation. It does not make network requests or run an expensive scan on activation.

Common workflows

• Open Tools > WP Doctor to inspect health and run a diagnosis.
• Run wp doctor status --format=json for an automation-friendly health summary.
• Run wp doctor scan --intensity=light for a bounded scan.
• Run wp doctor report --format=json to export a sanitized support report.
• Install the optional MU agent from Settings only when early recovery metadata is required.

All privileged web operations require both the manage_options capability and a valid WordPress REST nonce. REST responses are private and never expose raw stack traces, request bodies, credentials, cookies, or authorization headers.

Architecture

The root plugin file only establishes constants, loads the autoloader, and delegates to Core\\Plugin. Modules register their own WordPress hooks and depend on small explicit contracts. High-volume records live in indexed custom tables; options contain only bounded settings and schema state.

wp-doctor.php                 Plugin bootstrap
src/Core/                     Lifecycle, module registration, settings
src/Storage/                  Schema, repositories, retention
src/Security/                 Authorization, redaction, URL policy
src/Diagnostics/              Checks, scores, orchestration
src/Timeline/                 Change-event recording
src/Errors/                   Shutdown fatal capture
src/Reports/                  Privacy-safe exports
src/Rest/                     Versioned authenticated API
src/Cli/                      WP-CLI commands
src/Admin/                    WordPress admin application
src/Agent/                    Optional MU-agent installer/status
mu-agent/                     Minimal early bootstrap agent
tests/                        Unit and JavaScript tests
docs/                         Architecture, operations, and assurance docs

See Architecture, Development, and Data Model.

Development and validation

composer check
npm test
npm run validate
npm run package

composer check runs syntax checks, unit tests, PHPCS, and PHPStan when their installed executables are available. The CI workflow installs locked dependencies and requires every gate. Full WordPress integration, browser, accessibility, Plugin Check, and benchmark procedures are documented in Testing.

API and extension points

Authenticated endpoints are under /wp-doctor/v1; see REST API. WP-CLI commands are described in WP-CLI.

Integrators can add diagnostic checks with wp_doctor_diagnostic_checks, filter report data with wp_doctor_report_data, and observe recorded events with wp_doctor_event_recorded. Filters receive documented value objects or arrays and must not throw.

Security, privacy, and performance

• No telemetry or remote services are enabled.
• Sensitive values pass through centralized recursive redaction before storage or export.
• Passive monitoring performs no external network calls and no write on each normal page request.
• Raw diagnostic data is retained for a bounded period and pruned in batches.
• The optional MU agent is installed explicitly and removed only after its ownership marker and checksum are verified.

Read Security Architecture, Threat Model, Privacy, and Performance.

Compatibility and release

The intended matrix and the distinction between intended and actually tested environments are maintained in Compatibility. Packaging and release gates are in Release. Do not treat an unexecuted matrix cell as verified.

Contributing and support

Read CONTRIBUTING.md before proposing a change. Security issues must follow SECURITY.md. Operational help is in Troubleshooting.

WP Doctor is licensed under GPL-2.0-or-later. See LICENSE.