Diagnostics

A single page that smoke-tests most external integrations the Clockwork Control app uses — not literally every one, see the gap list below. Lives at /settings/diagnostics (gear menu → Diagnostics). Read-only on every check — no test mail, no webhooks posted, no writes. Safe to click “Run all again” as many times as you want.

What it tests

The page runs 27 checks in sequence and renders a row per check. Order matters: control checks first (DB, network, storage), then the integration-specific ones grouped by domain (cloud providers, then hosting APIs, then chat/SMS, then AI triage, then security-feed APIs) — so when several rows go red simultaneously and the network row at the top is also red, you know to look at the network before suspecting several tokens went bad at once.

As of the modularization roadmap, 16 of these checks are contributed by their respective modules/{Provider}/src/{Provider}ServiceProvider.php (or modules/BillCom/, modules/AiRemedy/) and merged in via Modules\Core\ModuleRegistry::diagnosticChecks() — they’re no longer hardcoded in DiagnosticsController: every cloud provider (Azure, Hetzner, DigitalOcean, Vultr, Linode), every hosting provider (Pressable, SpinupWP, WP Engine, Kinsta, Cloudways, GridPane), every chat/SMS notification channel (Mattermost, Slack, Twilio), Bill.com, and AiRemedy (OpenRouter). The other 11 checks (the 5 control checks, DigitalOcean Spaces, “Server provider values”, Cloudflare, and the 3 security-feed APIs) are still listed directly in DiagnosticsController::checks().

Status meanings

• OK (green) — check passed. Duration shown in ms.
• FAIL (red) — check ran and failed. The “Details” disclosure has the raw error.
• SKIP (grey) — integration isn’t configured (no env var, feature disabled). Not an error. If you expected it to be on, that’s the cue to set the env var.

What it doesn’t test

• Per-site Companion endpoints. Those live on each site’s page (/sites/{id} already has Companion health). Running 27 site probes here would drown the global signal.
• “Send a real test email.” Mutating actions belong behind their own explicit buttons, not silent every-page-load side effects. (When we add one, it’ll be a separate “Send test email to me” form next to the Mailer row.)
• Queue worker liveness. Not yet — the right “is the worker beating?” check needs a per-job heartbeat we don’t write yet.
• dist_url storage for the Companion package distribution. Will land here when the dist_url rollout flips on.
• GTmetrix, PageSpeed Insights, Spamhaus DBL. GTmetrix is on a metered plan with a per-day credit cap, and PSI is rate-limited; adding checks that consume scan credits on every diagnostics page load is avoided. Spamhaus DBL is a DNS lookup rather than an HTTP API.

Adding a new check

Each check is a class implementing App\Services\Diagnostics\DiagnosticCheck:

public function id(): string;          // stable lowercase-with-hyphens
public function name(): string;        // display label
public function description(): string; // one-line "what's being checked"
public function run(): CheckResult;

CheckResult::ok(), ::fail(), ::skipped() are the three constructors. Skipped is for “integration isn’t configured” — never use it for actual failures.

Where the new class goes depends on what it’s checking:

• Core check (not owned by any module — Sucuri, Google Safe Browsing, Cloudflare, DigitalOcean Spaces, wpvulnerability.net, etc.): add it directly to the checks() method in DiagnosticsController (in the order you want it to render).
• Module-owned check (a new cloud provider, hosting provider, or notification channel): implement hostingProvider()/cloudProvider()’s diagnostics sibling, diagnosticCheck(): ?DiagnosticCheck, on that module’s ModuleServiceProvider subclass. Modules\Core\ModuleRegistry::diagnosticChecks() picks it up automatically — nothing to add in DiagnosticsController itself. See modules/Azure/src/AzureServiceProvider.php for a cloud-provider example, modules/Mattermost/src/MattermostServiceProvider.php for a notification-channel one.

The runner catches Throwables, so a check that explodes mid-run becomes a fail row rather than a 500.

Why this exists

Before this page, “is the app actually wired up right?” required running php artisan tinker and poking each client manually. Now it’s one click. Especially useful after rotating a token, restoring from backup, or moving the app to a new box.