Download the PHP package hellocron/php without Composer

HelloCron PHP SDK

Official PHP SDK for HelloCron: cron job, heartbeat and uptime monitoring. Works with any framework or none - the only transport requirement is a PSR-18 HTTP client (Guzzle works out of the box).

Using Laravel? The hellocron/laravel package instruments the Scheduler automatically; this SDK is the universal building block for everything else.

Installation

If your project has no PSR-18 client yet, add one (Guzzle is the usual choice):

Wrap a job

An ingest key (ck_, from the panel) is all you need. Monitors are created automatically on first ping. The fastest way to monitor a job is to wrap it:

job() sends run before your callable, complete with the measured duration after it, and fail with the exception message if it throws. All three pings share a generated series id, so overlapping runs never pair up wrong. The callable's return value is passed through, its exceptions are rethrown - only the pings themselves are fail-safe.

Pings (dead man's switch)

For full control, send the pings yourself:

ping() never throws and never blocks for long: monitoring must not be able to take down the job it monitors. It returns false when the ping could not be sent. If you want the exception instead (in a monitoring-critical path), use pingOrFail(). Stream and custom events go through event(), which is fail-safe the same way (with eventOrFail() as the throwing variant):

Management API

Add a management key (mk_, scopes read + write) to manage monitors as code. Both keys are optional and independent - pass only what you use.

For the common case - "make sure this cron job has a monitor with sane settings" - use ensure(), an idempotent upsert by name:

Manifests are plain arrays shaped exactly like the API contract - the server is the single source of validation truth, so the SDK never gets stale on manifest rules.

Config as code

Keep your monitors in a version-controlled file and apply it on deploy. YAML and JSON are supported by extension; YAML needs composer require symfony/yaml:

Errors

Management calls throw typed exceptions with stable, machine-readable codes (never match on message text):

Unknown error codes map to ErrorCode::Unknown instead of failing, so new server-side codes never break existing SDK versions.

Configuration

Everything is a constructor argument; nothing is global:

Every exception the SDK throws implements HelloCron\Exception\HelloCronExceptionInterface, so one catch block covers them all.

Timeouts

PSR-18 has no timeout API, so timeouts belong to the HTTP client. When the SDK constructs the default Guzzle client itself, it sets a 2 s connect / 5 s request timeout - short on purpose, because ping() runs synchronously inside the job it monitors, and a down monitoring endpoint must cost seconds, not tens. If you inject your own client, its configuration wins and the timeouts become your responsibility:

Migrating from cronitor-php

The ping vocabulary is intentionally compatible (run / complete / fail / skip, duration, exit_code, host, series), so most call sites map one to one:

Differences to know about: monitors are addressed by name (created automatically on first ping), errors are typed exceptions with stable ErrorCode enums instead of raw responses, and the transport is any PSR-18 client rather than bundled cURL. See the migration guide for the platform-level differences.

Requirements

PHP 8.1+, ext-json, any PSR-18 HTTP client.

Links

• Documentation
• OpenAPI spec
• Changelog

License

MIT