Creating custom checks | laravel-health | Spatie

 SPATIE

  Laravel Health
=================

spatie.be/open-source

  [Docs](https://spatie.be/docs)  [Laravel-health](https://spatie.be/docs/laravel-health/v1)  Basic-usage  Creating custom checks

 Version   v1

 Other versions for crawler [v1](https://spatie.be/docs/laravel-health/v1)

- [ Introduction ](https://spatie.be/docs/laravel-health/v1/introduction)
- [ Support us ](https://spatie.be/docs/laravel-health/v1/support-us)
- [ Requirements ](https://spatie.be/docs/laravel-health/v1/requirements)
- [ Installation & setup ](https://spatie.be/docs/laravel-health/v1/installation-setup)
- [ Questions and issues ](https://spatie.be/docs/laravel-health/v1/questions-issues)
- [ Changelog ](https://spatie.be/docs/laravel-health/v1/changelog)
- [ About us ](https://spatie.be/docs/laravel-health/v1/about-us)

Usage
-----

- [ Registering your first check ](https://spatie.be/docs/laravel-health/v1/basic-usage/registering-your-first-check)
- [ Creating custom checks ](https://spatie.be/docs/laravel-health/v1/basic-usage/creating-custom-checks)
- [ Manually running checks ](https://spatie.be/docs/laravel-health/v1/basic-usage/manually-running-checks)
- [ Conditionally running or modifying checks ](https://spatie.be/docs/laravel-health/v1/basic-usage/conditionally-running-or-modifying-checks)
- [ Endpoints ](https://spatie.be/docs/laravel-health/v1/basic-usage/endpoints)
- [ Pausing and resuming checks ](https://spatie.be/docs/laravel-health/v1/basic-usage/pausing-and-resuming-checks)
- [ Registering the same check multiple times ](https://spatie.be/docs/laravel-health/v1/basic-usage/registering-the-same-check-multiple-times)
- [ Testing ](https://spatie.be/docs/laravel-health/v1/basic-usage/testing)

Storing results
---------------

- [ General ](https://spatie.be/docs/laravel-health/v1/storing-results/general)
- [ As JSON ](https://spatie.be/docs/laravel-health/v1/storing-results/in-a-json-file)
- [ In the cache ](https://spatie.be/docs/laravel-health/v1/storing-results/in-cache)
- [ In the database ](https://spatie.be/docs/laravel-health/v1/storing-results/in-the-database)
- [ Not storing results ](https://spatie.be/docs/laravel-health/v1/storing-results/not-storing-results)

Configuring notifications
-------------------------

- [ General ](https://spatie.be/docs/laravel-health/v1/configuring-notifications/general)
- [ Via mail ](https://spatie.be/docs/laravel-health/v1/configuring-notifications/via-mail)
- [ Via Slack ](https://spatie.be/docs/laravel-health/v1/configuring-notifications/via-slack)
- [ Via Oh Dear ](https://spatie.be/docs/laravel-health/v1/configuring-notifications/via-oh-dear)

Viewing check results
---------------------

- [ General ](https://spatie.be/docs/laravel-health/v1/viewing-results/general)
- [ On a webpage ](https://spatie.be/docs/laravel-health/v1/viewing-results/on-a-webpage)
- [ On the CLI ](https://spatie.be/docs/laravel-health/v1/viewing-results/on-the-cli)
- [ As JSON ](https://spatie.be/docs/laravel-health/v1/viewing-results/as-json)

Available checks
----------------

- [ Overview ](https://spatie.be/docs/laravel-health/v1/available-checks/overview)
- [ Backups ](https://spatie.be/docs/laravel-health/v1/available-checks/backups)
- [ Application Cache ](https://spatie.be/docs/laravel-health/v1/available-checks/cache)
- [ Cached config, routes, and events ](https://spatie.be/docs/laravel-health/v1/available-checks/cached-config-routes-and-events)
- [ CPU load ](https://spatie.be/docs/laravel-health/v1/available-checks/cpu-load)
- [ DB connection ](https://spatie.be/docs/laravel-health/v1/available-checks/db-connection)
- [ DB connection count ](https://spatie.be/docs/laravel-health/v1/available-checks/db-connection-count)
- [ DB size ](https://spatie.be/docs/laravel-health/v1/available-checks/db-size-check)
- [ DB table size ](https://spatie.be/docs/laravel-health/v1/available-checks/db-table-size-check)
- [ Debug mode ](https://spatie.be/docs/laravel-health/v1/available-checks/debug-mode)
- [ Environment ](https://spatie.be/docs/laravel-health/v1/available-checks/environment)
- [ Flare error count ](https://spatie.be/docs/laravel-health/v1/available-checks/flare-error-count)
- [ Horizon ](https://spatie.be/docs/laravel-health/v1/available-checks/horizon)
- [ Meilisearch ](https://spatie.be/docs/laravel-health/v1/available-checks/meilisearch)
- [ Ping ](https://spatie.be/docs/laravel-health/v1/available-checks/ping)
- [ Queue ](https://spatie.be/docs/laravel-health/v1/available-checks/queue)
- [ Redis ](https://spatie.be/docs/laravel-health/v1/available-checks/redis)
- [ Redis memory usage ](https://spatie.be/docs/laravel-health/v1/available-checks/redis-memory-usage)
- [ Schedule ](https://spatie.be/docs/laravel-health/v1/available-checks/schedule)
- [ Security advisories ](https://spatie.be/docs/laravel-health/v1/available-checks/security-advisories)
- [ Used disk space ](https://spatie.be/docs/laravel-health/v1/available-checks/used-disk-space)

Security
--------

- [ Using Secret Token ](https://spatie.be/docs/laravel-health/v1/security/using-secret-token)

 Creating custom checks
======================

###  On this page

1. [ Creating results ](#content-creating-results)
2. [ Adding a short summary ](#content-adding-a-short-summary)
3. [ Adding meta information ](#content-adding-meta-information)

This package offers [a few common checks](https://spatie.be/docs/laravel-health/v1/available-checks/overview) right out of the box. If you want to monitor another aspect of your app, you can create your own custom check.

A check is any class that extends from `Spatie\Health\Checks\Check`. It contains one abstract method that you should implement: `run`.

```
namespace App\Checks;

use Spatie\Health\Checks\Check;
use Spatie\Health\Checks\Result;

class YourCustomCheck extends Check
{
    public function run(): Result
    {
        // your custom logic...
    }
}
```

Creating results
--------------------------------------------------------------------------------------------------------

The `run` method should always return a `Spatie\Health\Checks\Result`. Using this object you can instruct the package to report a failure, to send a notification, and add meta information.

### Setting a status and sending notifications

The `Result` object has a `status` to signify a check is ok, produces a warning, or has failed.

You can use these methods to set the `status` of a result:

```
$result = Spatie\Health\Checks\Result::make();

$result->ok(); // the check ran ok
$result->warning(); // the check ran ok, but with a warning
$result->failed(); // the check failed
```

You should call `ok()` when everything your check verifies is ok. You should call `fail()` if you detected that there was something wrong. The `warning()` should be used when the check did pass, but might fail soon.

When you pass a string to any of these methods and return that result, then the package will send a notification.

Here's an example check that will check for used disk space. When used disk space is above 70%, a warning notification with a warning will be sent, when above 90% an error notification will be sent.

```
namespace App\Checks;

use Spatie\Health\Checks\Check;
use Spatie\Health\Checks\Result;

class UsedDiskSpaceCheck extends Check
{
    public function run(): Result
    {
        $usedDiskSpacePercentage = $this->getDiskUsagePercentage();

        $result = Result::make();

        if ($usedDiskSpacePercentage > 90) {
            return $result->failed("The disk is almost full ({$usedDiskSpacePercentage} % used)");
        }

        if ($usedDiskSpacePercentage > 70) {
            return $result->warning("The disk getting full ({$usedDiskSpacePercentage}% used)");
        }

        return $result->ok();
    }

    protected function getDiskUsagePercentage(): int
    {
        // determine used disk space, omitted for brevity
    }
}
```

Adding a short summary
--------------------------------------------------------------------------------------------------------------------------

Optionally, you can add a short summary of what the check found, using the `shortSummary` method.

```
namespace App\Checks;

use Spatie\Health\Checks\Check;
use Spatie\Health\Checks\Result;

public function run(): Result
{
    $usedDiskSpacePercentage = $this->getDiskUsagePercentage();

    $result = Result::make();

    $result->shortSummary("{$usedDiskSpacePercentage}%")

    // ...
}
```

This short summary will be written in [a result store](https://spatie.be/docs/laravel-health/v1/storing-results/general). The summary can be used when displaying all the results on a dashboard.

Adding meta information
-----------------------------------------------------------------------------------------------------------------------------

You can add meta information to a result. This meta information will be written in [a result store](https://spatie.be/docs/laravel-health/v1/storing-results/general). By adding meta information, external services like Oh Dear can display it in their notification, or you can keep a history of this meta information in your own database.

Meta information can be added to a check result, by calling `meta` and passing it with an array of meta data.

```
namespace App\Checks;

use Spatie\Health\Checks\Check;
use Spatie\Health\Checks\Result;

class UsedDiskSpaceCheck extends Check
{
    public function run(): Result
    {
        $usedDiskSpacePercentage = $this->getDiskUsagePercentage();

        $result = Result::make();

        $result->meta(['used_disk_space' => $usedDiskSpacePercentage]);

        // rest of the check omitted for brevity

        return $result;
    }
}
```