OK

Is your Laravel application OK? backstage/laravel-ok runs the health checks that answer that and notifies you when one of them fails. This package puts the answer on a page: every check the application has registered, with the result of the last time it ran.

• Every registered check, whether or not it has ever run. A check that is registered but never scheduled reads as "Not run", which is exactly the kind of thing worth finding out.
• What is broken comes first. Failed, then crashed, then never run, then fine.
• The last result, not a fresh one. Opening the page runs nothing: results are recorded as the checks run, on the schedule, from ok:check, or from the panel.
• Run one check, or all of them, from the page — for when you have just fixed something and want to know now.

How the results get there

laravel-ok keeps no history. It runs a check, notifies if it failed, and moves on. So this package listens for the CheckEnded event and writes the result of every check that ends to the cache, and the page is drawn from that.

That has one consequence worth knowing about: the cache store has to be one that survives between requests, and one the worker running the scheduled checks writes to as well. On the array store the page stays empty, and with Octane's per-process store it only shows what that process itself ran.

Installation

composer require backstage/ok

There is nothing to publish and no install command. This package's settings live under the config/ok.php it shares with laravel-ok, under keys laravel-ok does not use, and they are merged in with working defaults — see Configuration.

Registering the panel

Add the plugin to the Filament panel the overview should live on:

use Backstage\OK\OKPlugin;

$panel->plugins([
    OKPlugin::make()
        ->authorize(fn (): bool => (bool) auth()->user()?->is_admin),
]);

A check's message says what is wrong with the application — a disk that is nearly full, a package with a known vulnerability, a queue that stopped — so authorize() is where you decide who may read that. It defaults to everyone who can reach the panel, which is almost never what you want in production.

Running a check does real work: an audit shells out to composer or npm, a ping leaves the server. That is a separate question from being allowed to look, so it has its own switch:

OKPlugin::make()
    ->authorize(fn (): bool => (bool) auth()->user()?->is_admin)
    ->authorizeRunning(fn (): bool => (bool) auth()->user()?->is_owner)

Pass authorizeRunning(false) to make the overview read-only, and navigationItem(false) to keep it out of the panel's navigation and reach it from the user menu instead.

Registering checks

Which checks an application is judged by is laravel-ok's business, not this package's. Register them as you always would, in a service provider:

use Backstage\Laravel\OK\Checks\DiskSpaceCheck;
use Backstage\Laravel\OK\Checks\SchedulerCheck;
use Backstage\Laravel\OK\Facades\OK;

OK::checks([
    DiskSpaceCheck::config()->hourly(),
    SchedulerCheck::config()->everyMinute(),
]);

Everything registered there shows up on the page, including checks of your own.

Configuration

To change any of these, add them to the config/ok.php laravel-ok publishes, alongside its own notifications and checks keys:

// config/ok.php

'results' => [
    // The cache store the results are kept in. Null follows the
    // application's default store.
    'store' => env('OK_RESULTS_CACHE_STORE'),
],

'navigation' => [
    'group' => null,
    'sort' => null,
    'icon' => 'lucide-heart-pulse',
],

// How often the page refreshes itself. Null switches polling off.
'poll' => '60s',

Testing

composer test

License

The MIT License (MIT). Please see License File for more information.