masgeek/laravel-health-checker

Laravel health checker helper

1.0.2 2025-10-08 08:57 UTC

Requires

• php: >=8.2
• guzzlehttp/guzzle: ^7.8
• illuminate/cache: ^12.0
• illuminate/database: ^12.0
• illuminate/filesystem: ^12.0
• illuminate/http: ^12.0
• illuminate/log: ^12.0
• illuminate/mail: ^12.0
• illuminate/queue: ^12.0
• illuminate/redis: ^12.0
• illuminate/routing: ^12.0
• illuminate/support: ^12.0

MIT

• Munywele Sammy Barasa

README

A lightweight, configurable health-check endpoint for Laravel 12+.
Provides real-time diagnostics for critical services like database, cache, Redis, mail, queues, storage, and system resources.

🚀 Features

• Modular, configurable health checks
• JSON endpoint for integration with monitoring tools (Prometheus, Grafana, Kubernetes, etc.)
• Built-in support for:
  • Database connection and schema checks
  • Redis availability
  • Cache read/write
  • File storage read/write
  • Queue configuration
  • Mail transport
  • Disk usage (human-readable)
  • Pending migrations
  • Environment configuration
  • Loki server health
  • Log file write access

📦 Installation

Install via Composer:

  composer require masgeek/laravel-health-checker

⚙️ Configuration

Publish the configuration file:

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

Then edit config/healthcheck.php to configure your health 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),
    ],
    '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),
    ],
    'services' => [
        'loki_url' => env('LOKI_URL', null),
    ],
];

Each key corresponds to a built-in health check.

Disable what you don’t need by setting it to false.

🧠 Usage

A new route will be automatically registered:

  GET /health

Example response

{
  "status": "healthy",
  "timestamp": "2025-10-07T10:00:00Z",
  "checks": {
    "database": {
      "status": "UP",
      "database": "fuelrod",
      "schema": "public",
      "total_tables": 54
    },
    "redis": {
      "status": "UP",
      "version": "7.2.4"
    },
    "disk-space": {
      "status": "UP",
      "total_space": "500 GB",
      "free_space": "230 GB",
      "used_percentage": "54%"
    }
  }
}

🧩 Customization

• To disable specific checks, update config/healthcheck.php.

• To check Loki server health, define LOKI_URL in .env:

LOKI_URL=http://loki:3100