returnearly / laravel-nominal
Laravel package for Nominal heartbeat queue pings and Schedule::monitorWithNominal()
Requires
- php: ^8.4 || ^8.5
- dragonmantank/cron-expression: ^3.3
- illuminate/console: ^12.0|^13.0
- illuminate/contracts: ^12.0|^13.0
- illuminate/http: ^12.0|^13.0
- illuminate/support: ^12.0|^13.0
- returnearly/actions-pattern: ^2.0
- spatie/laravel-package-tools: ^1.16
Requires (Dev)
- larastan/larastan: ^3.0
- laravel/pint: ^1.14
- nunomaduro/collision: ^8.8
- orchestra/testbench: ^10.0|^11.0
- pestphp/pest: ^4.0
- pestphp/pest-plugin-arch: ^4.0
- pestphp/pest-plugin-laravel: ^4.0
- phpstan/extension-installer: ^1.4
- phpstan/phpstan-deprecation-rules: ^2.0
- phpstan/phpstan-phpunit: ^2.0
Suggests
None
Provides
None
Conflicts
None
Replaces
None
This package is auto-updated.
Last update: 2026-11-18 03:43:18 UTC
README
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.