brightfish / health-checks

0.10.0 2026-08-24 07:50 UTC

Requires

• php: ^8.3
• illuminate/config: ^12.30|^13.0
• illuminate/console: ^12.30|^13.0
• illuminate/contracts: ^12.30|^13.0
• illuminate/routing: ^12.30|^13.0
• illuminate/support: ^12.30|^13.0
• nesbot/carbon: ^3
• psr/simple-cache: ^2.0|^3.0

Requires (Dev)

• brianium/paratest: ^7.8
• laravel/pint: ^1.30
• nunomaduro/collision: ^8.9
• orchestra/testbench: ^10.6|^11.0
• phpstan/phpstan: ^2.2
• phpunit/phpunit: ^11.5|^12.5

GPL-3.0-only

• Arnaud Coolsaet

• laravel
• brightfish
• health-checks

Published on Packagist.org on 2026-08-24 07:50 UTC

README

Compatibility

Package	PHP	Laravel	Lumen
0.10.x	8.3, 8.4	12.x, 13.x	–
0.9.x	8.2+	12.x	–
0.8.x	8.0+	9.x, 10.x	yes

Lumen support was dropped in 0.10: there is no Lumen release for Laravel 12 or 13. Applications still on Laravel 10 or Lumen should stay on ^0.8.

Usage

Run all your registered checks from the command line:

php artisan health:check

Or make an HTTP request to the built-in health endpoint:

curl https://your.app/health

The endpoint returns 200 when every check passes. The first failing check aborts the run and returns its own message and HTTP status code as text/plain.

Installation

Install the package with composer:

composer require brightfish/health-checks

The service provider is registered automatically through package auto-discovery.

Publish the config file:

php artisan vendor:publish --tag="health-checks-config"

Create a custom health check class:

namespace App\Health;

class MyCustomCheck extends \Brightfish\HealthChecks\Checks\AbstractCheck
{
    public function run(): bool
    {
        return false;
    }

    public function getMessage(): string
    {
        return 'Error';
    }
}

Finally, list up the class in the config file:

return [
    'checks' => [
        \App\Health\MyCustomCheck::class,
    ],
];

Configuration

config/health.php holds three sections. The package ships defaults, so it works before you publish anything.

Key	Default	Description
checks	[]	Check classes, run in order. Each must extend AbstractCheck.
router.path	/health	Endpoint URI. Set to a falsy value to register no route at all.
router.middleware	[]	Middleware applied to the endpoint.
router.log_time	false	Record a timestamp every time a route is matched.
artisan.cmd_namespace	App\Console\Commands	Only commands in this namespace get their finish time recorded.
artisan.log_time	true	Record a timestamp whenever such a command finishes.

The route is registered under the name health.check.

Checking how long ago something ran

When artisan.log_time is on, the finish time of each of your own commands is cached. A check can read those timestamps through the protected helpers on AbstractCheck:

class ImportAgeCheck extends \Brightfish\HealthChecks\Checks\AbstractCheck
{
    public function run(): bool
    {
        $secondsDiff = $this->diffFromNow('app:import');

        if (is_null($secondsDiff) || $secondsDiff > 3600) {
            $this->setMessage('The import did not run in the last ' . $this->diffForHumans(3600));

            return false;
        }

        return true;
    }
}

getTime($key) returns the raw timestamp, diffFromNow($key) the age in seconds (or null if the key was never recorded), and diffForHumans($seconds) a readable duration.

Testing

composer test

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Brightfish
• All Contributors

License

GNU General Public License (GPL). Please see License File for more information.