PHPackages                             tahzeeb/laravel-heartbeat - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Logging & Monitoring](/categories/logging)
4. /
5. tahzeeb/laravel-heartbeat

ActiveLibrary[Logging & Monitoring](/categories/logging)

tahzeeb/laravel-heartbeat
=========================

Cron + queue monitoring (dead man's switch) client for Laravel.

v0.1.0(1mo ago)02MITPHPPHP ^8.2CI passing

Since Jul 18Pushed 1mo agoCompare

[ Source](https://github.com/tahzeeb536/laravel-heartbeat)[ Packagist](https://packagist.org/packages/tahzeeb/laravel-heartbeat)[ RSS](/packages/tahzeeb-laravel-heartbeat/feed)WikiDiscussions main Synced 2w ago

READMEChangelog (1)Dependencies (7)Versions (2)Used By (0)

Laravel Heartbeat
=================

[](#laravel-heartbeat)

[![Latest Version on Packagist](https://camo.githubusercontent.com/b9a076df993047cb333756f5d228e3484947e356f7137fa956242ba4e30b1216/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f7461687a6565622f6c61726176656c2d6865617274626561742e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/tahzeeb/laravel-heartbeat)[![Tests](https://camo.githubusercontent.com/6f23e1956504f63730672470273ad6402b2bbe6e42141182b880d4f58866a78f/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f7461687a6565623533362f6c61726176656c2d6865617274626561742f74657374732e796d6c3f6272616e63683d6d61696e266c6162656c3d7465737473267374796c653d666c61742d737175617265)](https://github.com/tahzeeb536/laravel-heartbeat/actions/workflows/tests.yml)[![Total Downloads](https://camo.githubusercontent.com/246e84aa506f23284d8ceae7feaff0d081ff512e00e1f3371befc84ee8179e5a/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f7461687a6565622f6c61726176656c2d6865617274626561742e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/tahzeeb/laravel-heartbeat)[![License](https://camo.githubusercontent.com/b383830facb04711be6ccd5d07eb85243f5138e380632b23128d9d41856f70d9/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f7461687a6565622f6c61726176656c2d6865617274626561742e7376673f7374796c653d666c61742d737175617265)](LICENSE)

A fail-safe **cron & queue monitor** for Laravel. Install it with one line, and it automatically watches your scheduled tasks and queued jobs and pings your Laravel Heartbeat endpoint when they start, finish, or fail — so you're alerted the moment a job breaks or silently stops running.

It's a *dead man's switch* for your background work: you find out when a task **didn't** run, not just when it errored.

> 🚧 **The hosted service is launching soon.** The client package below is production-ready today. Star the repo to follow along and get notified when sign-ups open.

Why
---

[](#why)

Most failures in a Laravel app happen where nobody's looking — a nightly command that quietly stopped firing after a deploy, or a queued job that's been failing for hours. Laravel Heartbeat closes that gap with three guarantees:

- **Zero config.** After install, every scheduled task is discovered and monitored automatically. No per-task boilerplate.
- **Catches the silent failures.** A scheduled command that exits non-zero *without throwing* still gets reported as failed — the case naive monitors miss and report as success.
- **Never breaks your app.** Every ping runs under a short timeout and swallows all errors. If the monitoring service is slow or down, your jobs run exactly as if this package weren't installed.

Requirements
------------

[](#requirements)

- PHP 8.2+
- Laravel 12 or 13

Installation
------------

[](#installation)

Install via Composer:

```
composer require tahzeeb/laravel-heartbeat
```

The service provider is registered automatically. Add your project key to `.env`:

```
HEARTBEAT_API_KEY=your-project-key
```

That's it — your scheduled tasks and queued jobs are now monitored.

> **Note:** By default the package only sends pings in the `production` environment (see [Configuration](#configuration)). To try it locally, add your current environment to the `environments` array.

Optionally publish the config file:

```
php artisan vendor:publish --tag=heartbeat-config
```

How it works
------------

[](#how-it-works)

Once installed, the package hooks into Laravel's own scheduler and queue events:

- **Scheduled tasks** — for every task in your schedule, it sends a `start` ping when the task begins, a `success` ping (with duration) when it finishes cleanly, and a `fail` ping if the task throws **or** exits with a non-zero code.
- **Queued jobs** — when a job fails permanently (after its retries are exhausted), it sends a `fail` ping. Failures of the same job class roll up into a single monitor, so a hundred failures show up as one red monitor, not a hundred.

Each monitor gets a stable, unique slug derived from the task or job, so it stays consistent across deploys and workers. For scheduled tasks, give a task an explicit name and the slug is derived from it instead of the raw command:

```
$schedule->command('reports:nightly')->dailyAt('01:00')->name('nightly-reports');
```

Manual pings
------------

[](#manual-pings)

For work that isn't a scheduled task or queued job — a long-running script, a step inside a bigger job — ping Heartbeat directly with the `Heartbeat` facade:

```
use Tahzeeb\Heartbeat\Facades\Heartbeat;

Heartbeat::start('nightly-import');

// ... do the work ...

Heartbeat::success('nightly-import', durationMs: 1250);
// or, on failure:
Heartbeat::fail('nightly-import', exitCode: 1, output: $exception->getMessage());
```

These calls are fail-safe like every other ping in the package (see [How it works](#how-it-works)) — they never throw, even if Heartbeat is unreachable or disabled.

Configuration
-------------

[](#configuration)

All configuration is optional except `api_key`. The published `config/heartbeat.php` supports:

KeyEnv varDefaultDescription`enabled``HEARTBEAT_ENABLED``true`Master on/off switch for all pings.`api_key``HEARTBEAT_API_KEY``null`Your project key. If empty, the package is a no-op.`url``HEARTBEAT_URL``https://api.laravelheartbeat.com/v1`The API base URL.`timeout``HEARTBEAT_TIMEOUT``2`Connect/read timeout in seconds. Keep it small.`monitor_scheduled_tasks`—`true`Auto-monitor the scheduler.`monitor_queue_failures`—`true`Ping on permanently failed queue jobs.`grace_period`—`60`Default seconds of grace before a monitor is considered late.`ignore`—`[]`Tasks/jobs to skip (see below).`environments`—`['production']`Only send pings in these app environments.### Ignoring tasks and jobs

[](#ignoring-tasks-and-jobs)

Add a command fragment, a monitor slug, or a job class to the `ignore` array to exclude it from monitoring entirely:

```
'ignore' => [
    'telescope:prune',         // matches the scheduled command
    'App\\Jobs\\LogCleanup',   // matches the job class
],
```

Commands
--------

[](#commands)

### `heartbeat:list`

[](#heartbeatlist)

Lists every monitor the package has discovered from your schedule, with its slug, name, cron expression, and type. Runs entirely offline — no network calls — so it's a safe way to preview exactly what will be monitored before you go live:

```
php artisan heartbeat:list
```

### `heartbeat:test`

[](#heartbeattest)

Sends a single test success ping (default slug `heartbeat-test`, override with `--slug`) so you can verify your API key and connectivity. Reports the outcome plainly, including the HTTP status on failure — and never throws:

```
php artisan heartbeat:test
php artisan heartbeat:test --slug=my-check
```

### `heartbeat:sync`

[](#heartbeatsync)

Enumerates monitors the same way `heartbeat:list` does and POSTs them to your Heartbeat dashboard, so it always knows about every scheduled task:

```
php artisan heartbeat:sync
```

Testing
-------

[](#testing)

```
composer test
```

The suite runs against Laravel 12 and 13 with no live network calls.

Contributing
------------

[](#contributing)

Contributions are welcome. Please make sure the tests and code style checks pass before opening a pull request:

```
composer test
composer format
```

Security
--------

[](#security)

If you discover a security vulnerability, please email **** instead of opening a public issue.

Credits
-------

[](#credits)

- [Tahzeeb Sattar](https://github.com/tahzeeb536)
- [All Contributors](../../contributors)

License
-------

[](#license)

The MIT License (MIT). Please see the [License File](LICENSE) for more information.

###  Health Score

35

—

LowBetter than 77% of packages

Maintenance91

Actively maintained with recent releases

Popularity2

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity36

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

46d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/53435829?v=4)[Tahzeeb Sattar](/maintainers/tahzeeb536)[@tahzeeb536](https://github.com/tahzeeb536)

---

Top Contributors

[![tahzeeb536](https://avatars.githubusercontent.com/u/53435829?v=4)](https://github.com/tahzeeb536 "tahzeeb536 (2 commits)")

---

Tags

schedulerlaravelmonitoringqueuecronheartbeatdead-man-switch

###  Code Quality

TestsPest

Static AnalysisPHPStan

Code StyleLaravel Pint

### Embed Badge

![Health badge](/badges/tahzeeb-laravel-heartbeat/health.svg)

```
[![Health](https://phpackages.com/badges/tahzeeb-laravel-heartbeat/health.svg)](https://phpackages.com/packages/tahzeeb-laravel-heartbeat)
```

###  Alternatives

[laravel/horizon

Dashboard and code-driven configuration for Laravel queues.

4.2k104.7M380](/packages/laravel-horizon)[laravel/sail

Docker files for running a basic Laravel application.

1.9k220.0M1.5k](/packages/laravel-sail)[anousss007/vigilance

A driver-agnostic control center for Laravel queues, jobs, commands and the scheduler. Monitor what ran (with parameters), see failures, and dispatch jobs or run artisan commands manually from a self-contained dashboard.

1949.9k](/packages/anousss007-vigilance)[laravel/ai

The official AI SDK for Laravel.

1.1k6.4M363](/packages/laravel-ai)[laravel/pulse

Laravel Pulse is a real-time application performance monitoring tool and dashboard for your Laravel application.

1.7k17.6M172](/packages/laravel-pulse)[spatie/laravel-health

Monitor the health of a Laravel application

89313.5M196](/packages/spatie-laravel-health)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)