Download the PHP package cronheart/wp without Composer

Cronheart for WordPress

Official WordPress plugin for cronheart.com — detect when WP-Cron silently stops firing and when individual scheduled events fail to complete.

Why

WP-Cron is request-driven. On a low-traffic site no requests arrive, no events fire, and a scheduled backup can be stalled for weeks before anyone notices. Uptime monitors do not catch this — the site responds to HTTPS just fine, it just is not running its jobs. Cronheart turns WP-Cron into a dead-man switch: the plugin pings cronheart.com every five minutes and on every individual event you register; if the pings stop, cronheart alerts you.

What's in the box

• Site heartbeat — a 5-minute custom WP-Cron event whose only job is to ping cronheart. Proves WP-Cron itself is alive and firing.

• Per-event monitoring — register any scheduled hook for start/success/fail pings:

• *`#[CRONHEART_]constants** — keep the per-monitor UUID (a write capability secret) out of the database and out of git history by defining it inwp-config.php`:

• Admin UI at Settings → Cronheart for sites without wp-config.php access.
• Monitor picker (since v0.2.0) — paste a cronheart.com API token (or define CRONHEART_API_TOKEN in wp-config.php) and the heartbeat field becomes a dropdown of your account's monitors instead of a hand-typed UUID. Entirely optional and gracefully degrading: no token — or any API error — falls back to the manual UUID field. The token is write-only in the UI and is never carried on the runtime ping path.
• Never breaks WP-Cron — every network / HTTP failure is folded into a logged warning. A broken cronheart backend cannot punish the host scheduler.
• PHP fatal capture — when a scheduled callback fatals, the fail ping body includes the error_get_last() summary so the cronheart dashboard shows the cause without you tailing debug.log.

Install

From WordPress.org (recommended)

WP Admin → Plugins → Add New → search "Cronheart" → Install Now → Activate. Or download cronheart.zip from the WordPress.org plugin page or a GitHub release and upload it under Plugins → Add New → Upload Plugin.

Then create a monitor on cronheart.com, copy the UUID, and either:

• Add it to wp-config.php:

• Or set it under Settings → Cronheart — paste the UUID, or, with an API token configured, pick the monitor from the dropdown.

Composer (developers)

Requirements

• WordPress ≥ 6.0
• PHP ≥ 8.2
• ext-curl (every reasonable WP install has it on)

Configuration

Source precedence

For both the heartbeat and per-event UUIDs:

An empty string at any level is treated as an explicit "do not monitor in this environment" signal — useful when the same plugin is deployed across dev / staging / prod and only prod should ping.

Constants

Per-event helper

Timing constraint. Hook enumeration runs at the very end of plugins_loaded (priority PHP_INT_MAX), so cronheart_monitor() calls must register from plugins_loaded or earlier — calls made from init or any later hook are missed by the instrumentation. Direct top-level calls in a mu-plugin or in your plugin's main file (before any add_action) are also fine.

Fail-ping reliability. Per-event fail pings are best-effort. The shutdown handler runs on PHP fatal errors, but the outbound HTTP request may not complete if PHP terminates abruptly (out-of- memory, segfault, FPM hard kill). Most fatals will surface on the cronheart dashboard; some edge cases will show as "silent stop" instead — at which point the heartbeat layer catches that the WP-Cron run itself never completed.

For coding agents

skills/add-cronheart/SKILL.md is a step-by-step recipe an AI coding agent (Claude Code, Cursor, Codex and the like) follows to add Cronheart to a WordPress site: install the plugin, attach the heartbeat monitor, add per-event monitors, connect a token for the admin screens, move WP-Cron onto a system cron and verify the first ping. It uses placeholders only — a real monitor UUID or API token never belongs in a repository. Copy the directory into your project's .claude/skills/, or point the agent at the file, and ask it to add Cronheart to the site. AGENTS.md at the repository root is the pointer agents read first. Neither ships in the WordPress.org zip: bin/build-release.sh strips skills/ from vendored packages and refuses to package the root copies.

Known limitations

• Vendor namespace prefixing is deferred. Today the bundled SDK ships under its canonical CronMonitor\… namespace; we'll reach for Strauss / php-scoper if a real collision is reported in the wild, at which point the SDK relocates to Cronheart\WP\Vendor\CronMonitor\…. Conflict risk is low because no other WP plugin currently bundles cron-monitor/php-sdk. Do not depend on the CronMonitor\… namespace from outside this plugin (e.g. another plugin reading our autoload) — that surface may move in a future minor release without warning.
• No WP-CLI commands yet — wp cronheart status / sync are on the roadmap.
• No multisite / network-activation handling yet. The plugin works on a single-site install.
• No Action Scheduler instrumentation — only WP-Cron hooks are monitored. WooCommerce stacks using Action Scheduler for tasks will not see those events on the cronheart dashboard yet.

Companion projects

• cron-monitor/php-sdk — the underlying PHP SDK this plugin wraps (also available standalone for Symfony / Laravel / plain-PHP cron jobs).
• cronheart.com — the SaaS backend.

Development

CI runs all four checks plus composer validate --strict and composer audit on PHP 8.2 / 8.3 / 8.4.

End-to-end smoke testing

Two flows depending on whether you have access to the cron-monitor backend source. External contributors use flow A (production); maintainers with backend access can use flow B (local) for faster iteration and full DB-level assertions.

A. Against production cronheart.com (public contributors)

The cron-monitor backend powering cronheart.com is a closed-source SaaS — public contributors cannot run a local copy. The default end-to-end verification path is therefore against the production service. It still validates the full plugin → SDK → wire-contract → backend pipeline; only the DB-level assertion is replaced with a dashboard check.

B. Against a local cron-monitor backend (maintainers only)

This flow requires checked-out access to the closed-source cron-monitor backend repository (sibling directory ../cron-monitor). Outside the cronheart maintainer team you do not have access — use flow A above.

The advantage of the local flow is full DB-level assertion: the smoke script reads back from the pings table and fails loudly if the expected rows are missing.

License

GPL-2.0-or-later — see LICENSE. Mandated by WordPress.org; the embedded cron-monitor/php-sdk is MIT-licensed and GPL-compatible.