laravel-nominal maintained by returnearly
Description
Laravel package for Nominal heartbeat queue pings and Schedule::monitorWithNominal()
Author
Last update
2026/11/18 03:25
(dev-master)
License
Downloads
1
Tags
Laravel Nominal
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,/errorfor crons) - GraphQL base is derived by stripping
/api/heartbeatfromurl_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:
- Ensures a Nominal heartbeat exists (GraphQL
createMonitor) named fromcron_name_pattern(default{app} - {env} - {cron}) - Sets
interval_secondsfrom the cron expression - Pings
/start, then/finishor/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.