zuvio / atlas

v0.1.0 2026-07-11 14:44 UTC

Requires

• php: >=7.4

Suggests

• laravel/framework: Enables the ->zuvioJob('slug') scheduler macro

MIT

• Zuvio Systems

• cron
• monitoring
• laravel
• job
• heartbeat
• atlas
• healthcheck
• zuvio

Published on Packagist.org on 2026-07-16 07:37 UTC

README

Report your scheduled PHP jobs to Zuvio Atlas — start, finish/fail, duration, and the exception message on failure — so Atlas can alert on failed, overrun, or missed runs. PHP 7.4+, no dependencies.

Install

composer require zuvio/atlas

Laravel

The service provider auto-registers a ->zuvioJob('slug') scheduler macro:

// routes/console.php or app/Console/Kernel.php
$schedule->command('backup:run')->daily()->zuvioJob('abc123');

It wires the scheduler's before / onSuccess / onFailure hooks to the start / finish / fail pings automatically.

Plain PHP

use Zuvio\Atlas\Atlas;

Atlas::run('abc123', function () {
    run_backup();          // start → finish on return, fail on exception
});

Manual control:

use Zuvio\Atlas\AtlasClient;

$atlas = new AtlasClient();               // baseUrl from ZUVIO_ATLAS_URL
$runId = $atlas->start('abc123');
try {
    do_work();
    $atlas->finish('abc123', $runId);
} catch (\Throwable $e) {
    $atlas->fail('abc123', $runId, 1, $e->getMessage());
    throw $e;
}

API-key mode (monitoring-as-code)

Pass a pm_live_ key (Pro+) to provision monitors from code and use a human key (auto-created on first ping) instead of a dashboard slug:

use Zuvio\Atlas\Atlas;
use Zuvio\Atlas\AtlasClient;

Atlas::configure(new AtlasClient(null, 10.0, null, getenv('ZUVIO_ATLAS_KEY')));
Atlas::put('nightly-backup', ['cronExpression' => '0 3 * * *']);   // idempotent
Atlas::run('nightly-backup', function () { run_backup(); });

Without a key, the identifier is a per-monitor slug on the unauthenticated capability URL.

Heartbeats

Atlas::heartbeat('important-heartbeat');                     // alive
Atlas::heartbeat('important-heartbeat', 'fail', 'disk full');

With an API key the id is a human key (auto-created on first ping); otherwise a slug. $atlas->putHeartbeat('key', ['interval' => 60]) provisions one from code.

Config

new AtlasClient($baseUrl, $timeout, $host, $apiKey). $baseUrl defaults to ZUVIO_ATLAS_URL (or https://atlas.zuviosystems.com); $apiKey to ZUVIO_ATLAS_KEY. Pings are best-effort — a monitoring outage never throws into your job.