# laravel-health: registered checks that notify before the outage

> laravel-health is a Spatie package that lets a Laravel application register health checks, run them on a schedule, and report a warning or a failure through a notification channel. The checks are plain PHP objects configured with threshold methods, and the shipped examples cover disk space, and the package is MIT licensed.

**spatie/laravel-health** — Check the health of your Laravel app

- Repository: https://github.com/spatie/laravel-health
- Website: https://spatie.be/docs/laravel-health
- Stars: 893 · Forks: 175
- Language: PHP
- License: MIT
- Published: 2026-10-20 · Updated: 2026-10-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/spatie-laravel-health

## A check is a registered object with two thresholds

The package description is one line, Check the health of your Laravel app, and the usage example shows the whole mechanism in about ten lines.

```php
use Spatie\Health\Facades\Health;
use Spatie\Health\Checks\Checks\UsedDiskSpaceCheck;

Health::checks([
    UsedDiskSpaceCheck::new()
        ->warnWhenUsedSpaceIsAbovePercentage(70)
        ->failWhenUsedSpaceIsAbovePercentage(90),
]);
```

The structure is worth reading carefully because it is the design. A check is a class, configured through named methods that read as a policy statement. warnWhenUsedSpaceIsAbovePercentage(70) and failWhenUsedSpaceIsAbovePercentage(90) are not configuration arrays, they are method calls that express intent directly.

There are two thresholds rather than one, and the documentation explains what they produce. When the used disk space is over 70 percent a notification with a warning is sent, and if it is above 90 percent you get an error notification.

That two stage design is the substance of the package. A single threshold gives you one alert when something is already broken. Two thresholds give you a warning while you still have time to react, and a failure only once the situation is genuinely degraded.

The registration itself is a call to the Health facade, typically in a service provider according to the comment in the example. The facade returns a fluent builder, and the array of checks is what you hand it.

This is the shape of the whole library, and it is worth noting what is not here. There is no configuration file in the readme, no JSON schema of check types, no automatic discovery. You register the checks you want, explicitly, with the thresholds you want. The trade is less machinery and more repetition, and for a package whose whole job is a short list of checks, that is usually the right way round.

## Notifications by mail and Slack out of the box

The documentation states that out of the box the package can notify you via mail and Slack.

That short sentence carries more design weight than it appears to. In Laravel, notification channels are a first class concept, so a health check firing a warning is not a bespoke integration but an ordinary notification that happens to be triggered by a scheduled job rather than by a user action. That means the channel configuration, the recipient list and the formatting are all handled by the framework's notification system, which is why two channels come for free.

The alternative would be a package that writes to a log file and expects you to ship that somewhere. That approach has the advantage of not needing mail server configuration inside a production application, which is often awkward, and the disadvantage of being invisible until someone wires up a log shipper.

Slack deserves a specific note because it is where most of the value lands in practice. A disk space warning is only useful if it reaches the person who can free the disk, and a Slack message to a team channel reaches them without anyone having to watch a mailbox. The mail channel is the fallback for teams without a chat tool.

The repository layout confirms the notification side is real rather than aspirational. There is a config/ directory for the package configuration, a database/ directory, which suggests the results are persisted rather than only dispatched, and resources/ with a css/health.css file for the styling of whatever the package renders.

That database directory is the piece to look at when evaluating. A health check that only notifies gives you a snapshot of a problem. A health check that records its history gives you a trend, which is what tells you whether a threshold you set is being crossed once a week or continuously.

## The web interface is a Tailwind build, not a Laravel Blade app

The package.json is small and tells you the front end story in one read.

```json
    "watch": "npx tailwindcss -i ./resources/css/health.css -o ./resources/dist/health.min.css --watch",
    "build": "npx tailwindcss -i ./resources/css/health.css -o ./resources/dist/health.min.css --minify"
```

Two scripts, one file in and one file out, both driven by npx tailwindcss, with Tailwind at 3.0.1 in devDependencies and the package marked private. There is a tailwind.config.js at the root and a postcss.config.js beside it.

So the package ships a small stylesheet, compiled by Tailwind, that renders somewhere in the application. It is a built asset rather than a set of Blade views with their own pipeline, which keeps the package from dragging a frontend build into every application that installs it.

The wording in the readme is careful here, it says the package can notify you via mail and Slack, and the web interface is implied by the resources and the css file rather than described in the visible documentation. The full picture is on the documentation site at spatie.be/docs/laravel-health, which the readme points to as the place where all documentation lives.

For an evaluator, the honest statement is that the readme documents the check registration and the notification channels, and everything else, the web interface, the configuration file contents, the list of available check types, is in the hosted documentation. That is a common shape for a package whose readme is a summary and whose docs site is the manual.

The tailwind.config.js and postcss.config.js are also worth noting for a second reason. They indicate the package expects a Tailwind project, or at least is designed to sit inside one, which is a small but real assumption about the host application.

## A Spatie package with a very specific support model

The funding section of the readme is more informative than it first appears, because it explains the shape of the project rather than just asking for money.

The package says a lot of resources are invested into creating best in class open source packages, and that you can support it by buying one of the paid products. There is a GitHub ads link, a link to spatie.be/open-source/support-us, and an invitation to send a postcard to their hometown, which they publish on a virtual postcard wall.

The postcard wall is a small joke that carries a large point. This is a company whose business is commercial packages and whose open source work is the funnel, so the questions to ask about this package are about longevity and about the commercial incentives behind it.

On longevity, the release history is reassuring. Versions 1.40.1 on 2026-07-22, 1.40.2 on 2026-08-07 and 1.40.3 on 2026-10-19, with the last push on 2026-10-19. Three patch releases across three months on a 1.40 line is the pattern of a package that is in production use and gets maintained accordingly, rather than one that is finished and left alone.

The credits name Freek Van der Herten alongside all contributors, which is the founder of Spatie, and the contributing and security sections point at the shared spatie/.github organisation for contribution guidelines and the security policy, which is the shape of a package that lives inside a broader maintained family.

## What this is not, and what it does not replace

Three boundaries are worth being clear about.

The first is scope. These are application health checks, not infrastructure monitoring. A check on used disk space tells you the application's filesystem is filling up. It does not tell you the host's CPU is saturated, that the queue is backed up, or that a dependency is slow. Those are different tools with different collectors and a different alert fatigue profile.

The second is what the checks actually measure. The example checks disk space against a percentage, which is a proxy for a failure mode rather than the failure mode itself. A more complete setup would check that the application can reach its database, that a specific queue is being consumed, or that a scheduled job ran. The readme's example shows the API, not the catalogue of checks, and the list of what ships is on the documentation site.

The third is the relationship to the platform health probe. A Laravel application behind a load balancer will usually have a route that returns a status code, and that route is what the balancer and the platform uptime check consult. The health package does not replace that, because the platform probe needs to answer in milliseconds and cannot depend on a scheduler running, and a health check whose failure is reported by email is no use to an autoscaler.

The alternatives section of the readme names two other packages, ans-group/laravel-health-check and Antonioribeiro/health, and the framing is friendly rather than competitive. Since the visible documentation does not describe how those differ in approach, it is worth reading their documentation directly rather than assuming either is a drop-in replacement.

## Conclusion

laravel-health suits a Laravel team that wants a small, explicit set of health signals with a clear escalation path, a warning threshold before a failure threshold, and notifications that do not require standing up a separate monitoring stack. It does not suit a team that wants full infrastructure monitoring, since the checks cover the application rather than the hosts, the network or the queue infrastructure around it, and it does not replace the load balancer health probe a platform already requires. Before adopting it, decide who receives the notifications, because the out of the box channels are mail and Slack and a check nobody is subscribed to is the same as no check at all.

## FAQ

### How do I register a health check in a Laravel app?

Call the Health facade, typically from a service provider, and hand it an array of check objects. Each check is configured fluently, for example UsedDiskSpaceCheck::new()->warnWhenUsedSpaceIsAbovePercentage(70)->failWhenUsedSpaceIsAbovePercentage(90).

### How does laravel-health notify me when a check fails?

Out of the box the package can notify you via mail and Slack. A check that crosses its warning threshold sends a warning notification, and crossing the failure threshold sends an error notification.

### Does laravel-health have a web interface?

The package ships styles built with Tailwind, from resources/css/health.css to resources/dist/health.min.css via the watch and build scripts in package.json, using Tailwind 3.0.1 with tailwind.config.js and postcss.config.js at the root. The full description of the interface is on the documentation site at spatie.be/docs/laravel-health.

### How often is laravel-health released?

The recent releases are 1.40.1 on 2026-07-22, 1.40.2 on 2026-08-07 and 1.40.3 on 2026-10-19, with the last push on 2026-10-19. The changelog is in CHANGELOG.md at the repository root.

### What licence does laravel-health use?

MIT, with a LICENSE.md file at the repository root. The package also points to a security policy for reporting vulnerabilities and to the shared contributing guidelines in the spatie/.github organisation.

## Sources

- [License: MIT](https://github.com/spatie/laravel-health/blob/main/LICENSE)
- [Project website](https://spatie.be/docs/laravel-health)
- [README](https://github.com/spatie/laravel-health/blob/main/README.md)
- [Releases](https://github.com/spatie/laravel-health/releases)
- [spatie/laravel-health on GitHub](https://github.com/spatie/laravel-health)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/spatie-laravel-health