WP Site Doctor

DevTools for WordPress health.

WP Site Doctor is an open-source, local-first diagnostic toolkit for WordPress.

Think of it as DevTools for your WordPress site.

It answers:

What is wrong with my WordPress site, why is it happening, how serious is it, and what can I safely do about it?

It is not another generic Site Health clone, a SaaS uptime monitor, or a one-click optimizer.

• No API key
• No account
• No SaaS
• No telemetry by default
• Nothing important leaves the site

---

Features

• Site diagnostics with a documented health score
• Database analysis (autoload size, table sizes, expired transients, revisions)
• Plugin and theme diagnostics
• WP-Cron analysis
• REST API and HTTP loopback diagnostics (this site only)
• Security checks (hardening signals, not a pentest)
• Accessibility and SEO diagnostics (not full WCAG or SEO suites)
• Debug log inspection for administrators
• Safe remediation with preview and confirmation
• HTML, JSON, and plain-text reports
• WP-CLI
• Extensible test registry for other developers

---

Status

0.1.0 is a developer preview. The scan engine, scoring, issue UI, core diagnostics, reports, REST API, and WP-CLI work. Deep scanners (full link crawl, unused media, plugin conflict detector) are registered as Not available yet. The plugin never invents fake scores.

---

Requirements

Item	Minimum
WordPress	6.4
PHP	8.0
Capability	manage_options (Administrator)

---

Installation

From this repository

1. Download the ZIP or clone the repo.

2. The plugin folder must be named wp-site-doctor and contain wp-site-doctor.php at the top level:

   wp-content/plugins/wp-site-doctor/wp-site-doctor.php

3. In wp-admin go to Plugins → Installed Plugins and activate WP Site Doctor.

4. Open Site Doctor in the admin menu.

5. Click Run Quick Scan.

Local by Flywheel

1. Start your site in Local.

2. Copy this project into:

   Local Sites/<site>/app/public/wp-content/plugins/wp-site-doctor/

3. Activate the plugin and open Site Doctor.

Do not nest an extra folder (plugins/WP Site Doctor/WP Site Doctor/). WordPress will not load it.

---

Quick start

1. Activate the plugin. It does not scan on activation or on every admin page load.
2. Open Site Doctor. First run is a welcome screen, not a fake 84 / 100.
3. Run Quick Scan.
4. On Overview, confirm a live score, issue counts, and category cards.
5. Open an issue. You should see what happened, why it matters, evidence, and a recommendation.

If those steps work, the plugin is running.

---

How it works

Scanner → Test Registry → Independent tests → Normalized results → Scoring → Issue store → UI

• Each diagnostic is isolated. A failed test becomes Diagnostic unavailable; the scan continues.
• The dashboard loads the cached latest scan. Expensive work only runs when you start a scan.
• Scores are a useful summary, not a scientific measurement. See docs/scoring.md.

Scan modes

Mode	When	What
Quick	First run	Fast PHP, WordPress, plugin/theme, autoload size, basic security
Full	User-started	All safe diagnostics
Deep	Confirm first	Expensive database / sample media work. Link crawl is not in 0.1

---

Diagnostic categories

PHP · WordPress · Database · Plugins · Themes · Cron · HTTP · REST · Security · Performance · Accessibility · SEO · Media · Debug

Passing a test means no issues were detected by this test. It does not mean the site is fully secure or perfectly optimized.

---

Privacy

Everything important runs inside WordPress.

• No analytics
• No telemetry
• No required external API
• Optional HTTP checks request this site’s home URL only

See docs/security.md.

---

Security

• REST namespace wp-site-doctor/v1 is administrator-only (manage_options + nonce).
• Reports redact passwords, tokens, and similar values.
• Medium/destructive fixes require preview and a confirmation token.
• 0.1 ships two remediations only: delete expired transients, and disable autoload on options listed in the latest scan.

This is a diagnostic tool, not a complete security scanner.

---

WP-CLI

wp site-doctor scan [--mode=quick|full|deep]
wp site-doctor issues [--severity=warning]
wp site-doctor score
wp site-doctor report [--format=json|txt|html]
wp site-doctor test database

---

REST API

Namespace: wp-site-doctor/v1
Permission: logged-in administrator. Not public.

Method	Route	Purpose
GET	/overview	Cached scan, job, history
POST	/scan	Start scan
POST	/scan/tick	Continue batch
GET	/scan/status	Progress
POST	/scan/cancel	Cancel
GET	/issues	Filtered issues
GET	/issues/{id}	Issue detail
POST	/issues/{id}	Ignore
POST	/fix/{id}	Preview or apply
POST	/report	HTML / JSON / text
GET	/search	Search last scan

JSON report schema: docs/json-schema.md.

---

Development

composer install
composer test
composer phpcs

Runtime JavaScript uses WordPress wp.element. You do not need Node to use the plugin.

Path	Purpose
docs/architecture.md	Engine layout and hooks
docs/diagnostics.md	Implemented vs stubbed tests
docs/scoring.md	Score formula
docs/security.md	Capabilities, SQL, redaction
CHANGELOG.md	Releases

---

Contributing

Please read CONTRIBUTING.md before opening a pull request.

Extension hook:

add_action( 'wp_site_doctor_register_test', function ( WP_Site_Doctor_Test_Registry $registry ) {
    $registry->add( new My_Custom_Test() );
} );

---

Roadmap

Version	Focus
0.1.0	Developer preview (this release)
0.2	Richer database doctor, debug viewer, security headers
0.3	Media analyzer, link checker, conflict detector
0.4	Broader safe fixes, backup integrations, multisite
1.0	Stable public API, extensions, WordPress.org readiness

---

License

GPL-2.0-or-later