README

mbs047/laravel-status-probe adds authenticated health and metadata endpoints to a Laravel application so it can be monitored by an external status system.

This package is meant to be installed inside the app you want to monitor. It does not create a public status page by itself. Instead, it exposes structured probe data that a status monitor can import or register against.

Documentation

docs/installation.md Installation, configuration, auth, routes, and heartbeat setup.
docs/connecting-to-monitor.md Pull and push registration flows for connecting the package to a status monitor.
docs/custom-contributors.md Extending the package with custom probe contributors.

What It Does

registers a health endpoint, default GET /status/health
registers a metadata endpoint, default GET /status/metadata
protects both endpoints with a bearer token by default
exposes built-in probes for app, db, and cache
supports optional heartbeat-driven probes for queue and scheduler
can push its registration payload to a remote monitor
supports custom contributors through a simple contract

Requirements

PHP ^8.2
Laravel 11, 12, or 13
a correct APP_URL value in the monitored application

Installation

composer require mbs047/laravel-status-probe
php artisan status-probe:install

The install command will:

publish config/status-probe.php
seed missing .env values
print the next steps for connecting to your monitor

Quick Start

After installation, make sure these values exist in your .env:

STATUS_PROBE_APP_ID=
STATUS_PROBE_TOKEN=
STATUS_PROBE_HEALTH_PATH=status/health
STATUS_PROBE_METADATA_PATH=status/metadata
STATUS_MONITOR_URL=
STATUS_MONITOR_TOKEN=
STATUS_MONITOR_VERIFY=true
STATUS_MONITOR_CA_PATH=

Important notes:

STATUS_PROBE_TOKEN protects the probe routes by default
APP_URL should be set correctly so the metadata payload contains valid URLs
STATUS_MONITOR_URL and STATUS_MONITOR_TOKEN are only needed if you want the monitored app to push its registration into a remote monitor
STATUS_MONITOR_VERIFY controls TLS certificate verification when the package calls the monitor over HTTPS
STATUS_MONITOR_CA_PATH lets you point to a local CA bundle when the monitor uses a private or self-signed certificate chain

Once installed, your app will expose:

GET /status/health
GET /status/metadata

Both routes use the configured middleware stack plus the package auth middleware. By default, that means the routes live in the api middleware group and require a bearer token.

Security

The default setup is intentionally private.

bearer token auth is enabled by default
requests without a valid token receive 401 Unauthorized
if the token is missing from config, the package returns 503 so the app does not silently expose an unprotected probe surface

Do not expose these endpoints publicly without understanding the tradeoff. Even if the data looks harmless, the probe surface reveals internals about your application runtime and infrastructure.

Health Payload

The health endpoint returns a single JSON payload with an overall status and a set of named checks:

{
  "overall_status": "operational",
  "generated_at": "2026-03-22T12:00:00+00:00",
  "service": {
    "name": "Billing API",
    "slug": "billing-api",
    "description": "Internal billing application"
  },
  "checks": {
    "app": {
      "label": "Application",
      "description": "Laravel application runtime bootstrap health.",
      "status": "operational",
      "summary": "Laravel application booted successfully.",
      "details": {}
    },
    "db": {
      "label": "Database",
      "description": "Primary database connection round trip.",
      "status": "operational",
      "summary": "Database query round trip succeeded.",
      "details": {}
    }
  }
}

Supported status values:

operational
degraded
partial_outage
major_outage

If a contributor throws an exception, the package catches it and reports that contributor as a major_outage instead of breaking the whole endpoint.

Metadata Payload

The metadata endpoint returns the registration contract a monitor can use to create services, components, and HTTP checks automatically.

It includes:

stable app_id
service name, slug, and description
the public health and metadata URLs
auth mode
component definitions
suggested HTTP check recipes for each component

Each component includes a status_json_path like checks.db.status, which lets the monitor read one probe status from the shared health payload.

Connecting To A Monitor

There are two common ways to connect this package to a monitor.

Pull Model

Your monitor fetches the metadata endpoint, reads the service/component definitions, and creates checks against the shared health URL.

For this model, you usually only need:

STATUS_PROBE_TOKEN
a correct APP_URL

Push Model

If your monitor accepts probe registrations, configure:

STATUS_MONITOR_URL=https://status.example.com
STATUS_MONITOR_TOKEN=your-monitor-token

Then run:

php artisan status-probe:register

That command posts the metadata payload to:

POST {STATUS_MONITOR_URL}/api/integrations/probes/register

Local HTTPS Development

If your monitor runs on a local HTTPS domain such as https://uptime.test with a self-signed or private CA certificate, registration may fail during the TLS handshake.

You have three safe options:

trust the local CA and point the package to it
disable monitor certificate verification in local development only
use the one-off insecure flag just for the registration command

Examples:

STATUS_MONITOR_VERIFY=false

STATUS_MONITOR_CA_PATH=/path/to/local-ca.pem

php artisan status-probe:register --insecure

Use --insecure only for local development. Prefer STATUS_MONITOR_CA_PATH when you have a local CA bundle available.

Built-In Contributors

Enabled by default:

app: verifies the Laravel app booted successfully
db: performs a database round trip with select 1
cache: performs a cache write/read/delete cycle

Available but disabled by default:

queue: checks freshness of a queue heartbeat written from the queue loop
scheduler: checks freshness of a scheduler heartbeat written from a command

You can toggle these in config/status-probe.php:

'contributors' => [
    'app' => true,
    'db' => true,
    'cache' => true,
    'queue' => true,
    'scheduler' => true,
],

Queue And Scheduler Heartbeats

Scheduler

Enable the scheduler contributor, then record a heartbeat every minute from your Laravel scheduler:

use Illuminate\Support\Facades\Schedule;

Schedule::command('status-probe:heartbeat scheduler')->everyMinute();

The scheduler contributor reports a failure if the heartbeat becomes older than heartbeat.scheduler_max_age_seconds.

Queue

Enable the queue contributor and run a normal Laravel queue worker. The package listens to the worker loop and refreshes a queue heartbeat while the worker is alive.

The queue contributor reports a failure if the heartbeat becomes older than heartbeat.queue_max_age_seconds.

For multi-server or container deployments, use a shared cache store for heartbeat data if your queue workers and HTTP app instances do not share local state.

Configuration

The published config file is config/status-probe.php.

Main options:

app_id: stable identifier for the monitored app
service_name, service_slug, service_description: service metadata
health_path, metadata_path: route paths
middleware: middleware stack used for the probe routes
auth.mode, auth.token: route auth configuration
monitor.url, monitor.token: remote monitor registration settings
monitor.interval_minutes, timeout_seconds, failure_threshold, recovery_threshold: defaults exposed in metadata for monitor-created checks
heartbeat.store: optional cache store for heartbeats
heartbeat.queue_max_age_seconds, heartbeat.scheduler_max_age_seconds: stale-heartbeat thresholds

Custom Contributors

You can add your own contributors for app-specific dependencies such as search, object storage, Redis, or external upstreams.

Implement Mbs047\LaravelStatusProbe\Contracts\ProbeContributor, bind it in the container, and tag it with status-probe.contributors:

use Mbs047\LaravelStatusProbe\Contracts\ProbeContributor;
use Mbs047\LaravelStatusProbe\Enums\ProbeStatus;
use Mbs047\LaravelStatusProbe\ProbeResult;

$this->app->singleton(SearchProbe::class, function () {
    return new class implements ProbeContributor
    {
        public function key(): string
        {
            return 'search';
        }

        public function label(): string
        {
            return 'Search';
        }

        public function description(): ?string
        {
            return 'Search cluster availability.';
        }

        public function defaultCheckConfig(): array
        {
            return [];
        }

        public function resolve(): ProbeResult
        {
            return new ProbeResult(ProbeStatus::Operational, 'Search is healthy.');
        }
    };
});

$this->app->tag(SearchProbe::class, 'status-probe.contributors');

Custom contributors automatically appear in both:

the health payload
the metadata payload used for registration/import

Commands

php artisan status-probe:install Publishes config and seeds missing environment values.
php artisan status-probe:register Pushes the registration payload to the configured monitor.
php artisan status-probe:heartbeat scheduler Records a scheduler heartbeat timestamp.

Testing

composer test

License

MIT

mbs047 / laravel-status-probe

Maintainers

Package info

Statistics

Security

README

Documentation

What It Does

Requirements

Installation

Quick Start

Security

Health Payload

Metadata Payload

Connecting To A Monitor

Pull Model

Push Model

Local HTTPS Development

Built-In Contributors

Queue And Scheduler Heartbeats

Scheduler

Queue

Configuration

Custom Contributors

Commands

Testing

License