Search by

returnearly / laravel-nominal

tomschlick

Laravel package for Nominal heartbeat queue pings and Schedule::monitorWithNominal()

Package info

github.com/returnearly/laravel-nominal

pkg:composer/returnearly/laravel-nominal

Statistics

Installs: 1

Dependents: 0

Suggesters: 0

Stars: 0

Open Issues: 0

v1.0.1 2026-11-18 02:25 UTC

This package is auto-updated.

Last update: 2026-11-18 03:43:18 UTC


README

Latest Version on Packagist GitHub Tests Action Status

Ping Nominal heartbeats from Laravel queues and scheduled tasks.

  • Dispatch a heartbeat job onto each configured queue (nominal:queue-heartbeats)
  • Wrap schedule entries with ->monitorWithNominal() (auto-register + start/finish/error)
  • Fail-soft: Nominal outages never fail your jobs or crons

Business logic lives in Actions via returnearly/actions-pattern.

Requirements

  • PHP 8.4 or 8.5
  • Laravel 12 or 13

Installation

composer require returnearly/laravel-nominal

Publish the config:

php artisan vendor:publish --tag="nominal-config"

Configuration

config/nominal.php:

return [
    'url_prefix' => env('NOMINAL_URL_PREFIX', 'https://nominal.example/api/heartbeat'),

    'headers' => [
        // 'Authorization' => 'Bearer '.env('NOMINAL_TOKEN'),
        // 'CF-Access-Client-Id' => env('CF_ACCESS_CLIENT_ID'),
        // 'CF-Access-Client-Secret' => env('CF_ACCESS_CLIENT_SECRET'),
    ],

    'queues' => [
        // 'default',
        // 'mail',
    ],

    'auto_register_queues' => env('NOMINAL_AUTO_REGISTER_QUEUES', false),
    'queue_interval_seconds' => (int) env('NOMINAL_QUEUE_INTERVAL_SECONDS', 60),
    'cron_name_pattern' => env('NOMINAL_CRON_NAME_PATTERN', '{app} - {env} - {cron}'),
    'timeout_seconds' => 5,
];
  • Heartbeat URLs: {url_prefix}/{slug} (and /start, /finish, /error for crons)
  • GraphQL base is derived by stripping /api/heartbeat from url_prefix
  • Auth is headers-only (no dedicated API token key)

In Nominal, create heartbeat monitors whose slug matches each sanitized queue name (or enable auto_register_queues).

Queue heartbeats

Schedule the command (for example every minute):

use Illuminate\Support\Facades\Schedule;

Schedule::command('nominal:queue-heartbeats')->everyMinute();

Or run it manually:

php artisan nominal:queue-heartbeats

The command dispatches SendQueueHeartbeatJob onto each configured queue. When a worker processes that queue, the job POSTs {url_prefix}/{sanitized-queue-name}.

Schedule monitoring

use Illuminate\Support\Facades\Schedule;

Schedule::command('reports:send')
    ->hourly()
    ->monitorWithNominal(); // name defaults to description/command

Schedule::call(fn () => null)
    ->dailyAt('02:00')
    ->name('Nightly cleanup')
    ->monitorWithNominal('Nightly cleanup');

On each run the package:

  1. Ensures a Nominal heartbeat exists (GraphQL createMonitor) named from cron_name_pattern (default {app} - {env} - {cron})
  2. Sets interval_seconds from the cron expression
  3. Pings /start, then /finish or /error

Failures talking to Nominal are logged and ignored so the scheduled task still runs (and still surfaces its own exceptions).

Architecture

Layer Classes
Entrypoints QueueHeartbeatsCommand, SendQueueHeartbeatJob, MonitorsWithNominal
Actions DispatchQueueHeartbeats, SendQueueHeartbeat, PingHeartbeat, EnsureHeartbeatMonitor, StartScheduledHeartbeat, FinishScheduledHeartbeat, FailScheduledHeartbeat
Collaborators NominalClient, Slug, CronInterval, MonitorName

Testing

composer test

License

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