README

A lightweight, configurable health-check endpoint for Laravel 12+ and Laravel 13+. It provides JSON diagnostics for application dependencies and system resources through an HTTP endpoint and Artisan command.

Features

Configurable core and infrastructure checks
JSON endpoint for Prometheus, Grafana, Kubernetes, and other monitoring systems
Database connection and table checks
Cache read/write checks with automatic cleanup
File storage read/write checks with automatic cleanup
Queue connection checks
Mail transport checks
Disk-space checks with configurable paths
Pending migration detection
Environment and PHP extension checks
Redis and Loki checks
Failed-job count, recent failure, and oldest failure details
Configured outbound dependency checks with bounded timeouts
TLS certificate expiration checks
Configuration cache state
Build version and commit metadata
Log file write access
Rate-limited health endpoint with minimal public output
Optional detailed output for trusted monitoring systems

Installation

Install via Composer:

composer require masgeek/laravel-health-checker

The service provider is auto-discovered by Laravel.

Configuration

Publish the configuration file:

php artisan vendor:publish --tag=healthcheck-config

Edit config/healthcheck.php in the application to enable or disable checks:

return [
    'core' => [
        'database' => env('HEALTHCHECK_DATABASE', true),
        'cache' => env('HEALTHCHECK_CACHE', true),
        'queue' => env('HEALTHCHECK_QUEUE', true),
        'mail' => env('HEALTHCHECK_MAIL', false),
        'migrations' => env('HEALTHCHECK_MIGRATIONS', true),
        'env-config' => env('HEALTHCHECK_ENV_CONFIG', true),
        'failed-jobs' => env('HEALTHCHECK_FAILED_JOBS', false),
    ],
    'infrastructure' => [
        'redis' => env('HEALTHCHECK_REDIS', false),
        'storage' => env('HEALTHCHECK_STORAGE', true),
        'disk-space' => env('HEALTHCHECK_DISK_SPACE', true),
        'logging' => env('HEALTHCHECK_LOGGING', true),
        'loki' => env('HEALTHCHECK_LOKI', false),
        'outbound' => env('HEALTHCHECK_OUTBOUND', false),
        'certificate' => env('HEALTHCHECK_CERTIFICATE', false),
        'config-cache' => env('HEALTHCHECK_CONFIG_CACHE', false),
        'build' => env('HEALTHCHECK_BUILD', false),
    ],
];

Checks that require application-specific configuration are opt-in by default. Configure their settings in the services section:

'services' => [
    'loki_url' => env('LOKI_URL', null),
    'outbound_urls' => [
        'https://api.example.com/health',
    ],
    'outbound_timeout' => 3,
    'certificate_host' => env('HEALTHCHECK_CERTIFICATE_HOST', null),
    'certificate_port' => 443,
    'certificate_warning_days' => 14,
    'build_version' => env('HEALTHCHECK_BUILD_VERSION', null),
    'build_commit' => env('HEALTHCHECK_BUILD_COMMIT', null),
],

Set healthcheck.failed_jobs_recent_minutes to control the recent-failure window.

Usage

The package automatically registers:

GET /health

The route is rate-limited by default with throttle:60. Configure the path and middleware with HEALTHCHECK_PATH and HEALTHCHECK_MIDDLEWARE.

Public responses return the overall status, timestamp, and check statuses without operational details. Enable detailed output only for trusted monitoring access:

HEALTHCHECK_EXPOSE_DETAILS=true

Example minimal response:

{
  "status": "healthy",
  "timestamp": "2025-10-07T10:00:00Z",
  "checks": {
    "database": {
      "status": "UP"
    },
    "cache": {
      "status": "UP"
    }
  }
}

When HEALTHCHECK_EXPOSE_DETAILS=true, the response includes driver names, database metadata, paths, versions, and error details.

Artisan command

Run the same checks from the command line:

php artisan health:check
php artisan health:check --json

The command returns exit code 0 when all enabled checks are UP and exit code 1 otherwise. The JSON option also returns the corresponding exit code.

Environment variables

Common optional variables include:

HEALTHCHECK_FAILED_JOBS=true
HEALTHCHECK_OUTBOUND=true
HEALTHCHECK_CERTIFICATE=true
HEALTHCHECK_CERTIFICATE_HOST=example.com
HEALTHCHECK_CONFIG_CACHE=true
HEALTHCHECK_BUILD=true
HEALTHCHECK_BUILD_VERSION=1.2.3
HEALTHCHECK_BUILD_COMMIT=abc123
HEALTHCHECK_PATH=health
HEALTHCHECK_MIDDLEWARE=throttle:60
HEALTHCHECK_EXPOSE_DETAILS=false
LOKI_URL=http://loki:3100

Use HTTPS for outbound URLs and certificate checks. Checks that make network requests have bounded timeouts.

Development

Install dependencies and run the Pest suite:

composer install
composer test

The test runner uses the explicit phpunit.xml configuration. Run the quality checks with:

composer analyse
composer lint
composer format
composer validate

PHP syntax checks can be run with:

for file in src/*.php src/*/*.php src/*/*/*.php; do php -l "$file" || exit 1; done

License

This package is open-sourced software licensed under the MIT license.

masgeek / laravel-health-checker

Package info

Security

Statistics