README

Vigilant WordPress Healthchecks

A WordPress plugin that provides a healthcheck endpoint for any site and integrates seamlessly with Vigilant.

Features

• Secure REST endpoint (/wp-json/vigilant/v1/health) protected by a bearer token.
• Built-in scheduler heartbeat that verifies WP-Cron is running and reports failures back to Vigilant.
• Extensible registry so you can add your own checks or metrics alongside the built-in catalogue.

Configuration

API token

• Navigate to Settings → Vigilant Healthchecks and paste the token generated by Vigilant or use your own if you do not use Vigilant.
• Every request to the health endpoint must send Authorization: Bearer <token>.

Checks and metrics

• The settings page lists all available checks and metrics; toggle anything you do not need.
• Disabled checks are never instantiated, reducing overhead on constrained installs.

Scheduler heartbeat

• The plugin registers vigilant_healthchecks_cron_monitor, which is scheduled every minute.
• When WP-Cron runs, the last heartbeat timestamp is stored and surfaced through the Cron check.
• Adjust the allowed delay via the vigilant_healthchecks_cron_threshold filter (default 5 minutes).
• If you disable WP-Cron, ensure a system cron invokes wp cron event run --due-now so the monitor continues to run.

Usage

REST endpoint

The health payload is exposed via the WordPress REST API:

POST /wp-json/vigilant/v1/health

Example request:

curl -X POST "https://example.com/wp-json/vigilant/v1/health" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json"

A 401 Unauthorized response indicates the token has not been configured or is invalid.

Registering custom checks and metrics

Hook into vigilant_healthchecks_prepare to register additional checks or metrics before the payload is assembled:

use Vigilant\HealthChecksBase\Checks\Metric;
use Vigilant\WordpressHealthchecks\HealthCheckRegistry;

add_action('vigilant_healthchecks_prepare', function (HealthCheckRegistry $registry): void {
    $registry->registerCheck(MyCustomCheck::make());
    $registry->registerMetric(MyCustomMetric::make());
});

Custom checks must extend Vigilant\HealthChecksBase\Checks\Check, while metrics extend Vigilant\HealthChecksBase\Checks\Metric.

Check availability

Each check self-reports whether it can run (for example, the Redis check requires the PHP Redis extension). Inapplicable checks are skipped automatically so they do not produce noise in Vigilant.

Available Checks

Available Metrics

Events & Filters

• vigilant_healthchecks_prepare - add or remove checks and metrics programmatically.
• vigilant_healthchecks_cron_threshold - override the maximum seconds between cron heartbeats.
• vigilant_healthchecks_database_size_cache_ttl - change the TTL (seconds) for cached database size calculations.
• vigilant_healthchecks_force_core_update_check / vigilant_healthchecks_force_plugin_update_check - force WordPress to refresh update metadata before running the respective checks.

Development Environment

A ready-to-use Docker setup lives in devenv/.

1. Ensure Docker is running.
2. Start the stack:

   docker compose -f devenv/docker-compose.yml up --build

3. Visit http://localhost:8000 (WordPress admin: admin / secret).
4. The plugin is mounted from your working copy and activated automatically; configure the token from the settings page and test the endpoint locally:

   curl -X POST "http://localhost:8000/wp-json/vigilant/v1/health" \
     -H "Authorization: Bearer YOUR_TOKEN" \
     -H "Content-Type: application/json"

Quality

Install dependencies and run the existing toolchain:

composer install
./vendor/bin/phpunit
./vendor/bin/phpstan analyse

Security Vulnerabilities

Please review our security policy for details on how to report vulnerabilities.

Credits

• Vincent Boon
• All Contributors

License

The MIT License (MIT). Please see License File for more information.