PHPackages                             mrtolouei/laravel-service-health - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Logging & Monitoring](/categories/logging)
4. /
5. mrtolouei/laravel-service-health

ActiveLibrary[Logging & Monitoring](/categories/logging)

mrtolouei/laravel-service-health
================================

A Laravel package for monitoring the health of databases, Redis, queues, filesystems, and external HTTP services.

v1.0.0(1mo ago)04MITPHPPHP >=8.2CI passing

Since May 8Pushed 1mo agoCompare

[ Source](https://github.com/mrtolouei/laravel-service-health)[ Packagist](https://packagist.org/packages/mrtolouei/laravel-service-health)[ RSS](/packages/mrtolouei-laravel-service-health/feed)WikiDiscussions master Synced 1w ago

READMEChangelog (1)Dependencies (8)Versions (2)Used By (0)

Laravel Service Health
======================

[](#laravel-service-health)

[![License](https://camo.githubusercontent.com/7013272bd27ece47364536a221edb554cd69683b68a46fc0ee96881174c4214c/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d626c75652e737667)](LICENSE)[![Tests](https://github.com/mrtolouei/laravel-service-health/actions/workflows/tests.yml/badge.svg)](https://github.com/mrtolouei/laravel-service-health/actions/workflows/tests.yml)[![Latest Stable Version](https://camo.githubusercontent.com/78b7e037f5e99c877a0465656fe60221ffba215cc1ea0bb40427e5d868e1a362/68747470733a2f2f706f7365722e707567782e6f72672f6d72746f6c6f7565692f6c61726176656c2d736572766963652d6865616c74682f762f737461626c65)](https://packagist.org/packages/mrtolouei/laravel-service-health)

A flexible and extensible **service health monitoring package for Laravel**.

This package helps you monitor the health of your application's critical services such as:

- Database connections
- Cache stores
- Queue connections
- Filesystem disks
- Redis connections
- External/internal HTTP endpoints

It includes:

- A web-based **dashboard**
- A **JSON API endpoint**
- An **Artisan command** for CLI / CI usage
- Built-in **authorization layer**
- Extensible architecture for adding **custom inspectors**

---

Screenshot
----------

[](#screenshot)

[![Laravel Service Health Dashboard](./screenshot.png)](./screenshot.png)

---

Table of Contents
-----------------

[](#table-of-contents)

- [Features](#features)
- [Requirements](#requirements)
- [Installation](#installation)
- [Publishing Assets](#publishing-assets)
    - [Publish Config](#publish-config)
    - [Publish Authorization Provider Stub](#publish-authorization-provider-stub)
    - [Publish Views](#publish-views)
- [Quick Start](#quick-start)
- [Routes](#routes)
- [Configuration](#configuration)
    - [Top-Level Config Options](#top-level-config-options)
    - [Monitor Configuration](#monitor-configuration)
- [Usage Examples](#usage-examples)
    - [Monitoring Multiple Database Connections](#monitoring-multiple-database-connections)
    - [Monitoring External APIs](#monitoring-external-apis)
    - [Monitoring Internal Services with Auth](#monitoring-internal-services-with-auth)
- [Dashboard](#dashboard)
- [JSON API](#json-api)
- [Artisan Command](#artisan-command)
- [Authorization](#authorization)
- [Custom Inspectors for Developers](#custom-inspectors-for-developers)
    - [Inspector Contract](#inspector-contract)
    - [Creating a Custom Inspector](#creating-a-custom-inspector)
    - [Registering a Custom Inspector](#registering-a-custom-inspector)
    - [Returning Rich Metadata](#returning-rich-metadata)
- [Status Model](#status-model)
- [CI Ideas](#ci-ideas)
- [Testing](#testing)
- [Contributing](#contributing)
- [License](#license)

---

Features
--------

[](#features)

- Monitor important Laravel services in one place
- Detect:
    - healthy services
    - degraded services
    - failed services
- Measure response duration in milliseconds
- Configure slow thresholds per monitor
- Expose health results through:
    - Dashboard page
    - API endpoint
    - CLI command
- Protect access using authorization middleware
- Add your own custom service inspectors
- Works with Laravel auto-discovery

---

Requirements
------------

[](#requirements)

- PHP `>= 8.2`
- Laravel `11`, `12`, or `13`

Package dependencies include:

- `illuminate/support`
- `illuminate/http`
- `illuminate/cache`
- `illuminate/queue`
- `illuminate/filesystem`
- `illuminate/database`

---

Installation
------------

[](#installation)

Install the package via Composer:

```
  composer require mrtolouei/laravel-service-health
```

Laravel will automatically discover and register the package service provider.

---

Publishing Assets
-----------------

[](#publishing-assets)

### Publish Config

[](#publish-config)

Publish the package configuration file:

```
  php artisan vendor:publish --tag=service-health-config
```

This creates:

```
config/service-health.php

```

### Publish Authorization Provider Stub

[](#publish-authorization-provider-stub)

If you want to define who can access the dashboard and API, publish the authorization provider stub:

```
  php artisan vendor:publish --tag=service-health-provider
```

This creates:

```
app/Providers/HealthServiceServiceProvider.php

```

You can then register your own gate logic there.

### Publish Views

[](#publish-views)

If you want to customize the dashboard UI:

```
  php artisan vendor:publish --tag=service-health-views
```

---

Quick Start
-----------

[](#quick-start)

### 1) Install the package

[](#1-install-the-package)

```
  composer require mrtolouei/laravel-service-health
```

### 2) Publish assets

[](#2-publish-assets)

```
  php artisan vendor:publish --tag=service-health-config
  php artisan vendor:publish --tag=service-health-provider
  php artisan vendor:publish --tag=service-health-views
```

### 3) Visit the dashboard

[](#3-visit-the-dashboard)

- Dashboard: `/service-health`
- API: `/service-health-api`

### 4) Run checks from CLI

[](#4-run-checks-from-cli)

```
  php artisan service-health:check
```

### 5) Optionally secure access

[](#5-optionally-secure-access)

Publish the authorization provider and define your gate rules.

---

Routes
------

[](#routes)

By default, the package registers two routes:

```
GET /service-health
GET /service-health-api

```

These are configurable via:

```
'route' => [
    'prefix' => env('SERVICE_HEALTH_ROUTE_PREFIX', ''),
    'dashboard' => env('SERVICE_HEALTH_ROUTE_DASHBOARD', 'service-health'),
    'api' => env('SERVICE_HEALTH_ROUTE_API', 'service-health-api'),
    'middleware' => [
        'web',
        MrTolouei\ServiceHealth\Http\Middleware\Authorize::class,
    ],
],
```

### Example

[](#example)

If you set:

```
SERVICE_HEALTH_ROUTE_PREFIX=admin/tools
SERVICE_HEALTH_ROUTE_DASHBOARD=health
SERVICE_HEALTH_ROUTE_API=health-api
```

Routes become:

- `/admin/tools/health`
- `/admin/tools/health-api`

---

Configuration
-------------

[](#configuration)

Main config file:

```
config/service-health.php

```

### Top-Level Config Options

[](#top-level-config-options)

#### enabled

[](#enabled)

```
'enabled' => env('SERVICE_HEALTH_ENABLED', true),
```

Globally enables or disables the package routes.

If set to false, routes will not be registered.

#### route

[](#route)

```
'route' => [
    'prefix' => env('SERVICE_HEALTH_ROUTE_PREFIX', ''),
    'dashboard' => env('SERVICE_HEALTH_ROUTE_DASHBOARD', 'service-health'),
    'api' => env('SERVICE_HEALTH_ROUTE_API', 'service-health-api'),
    'middleware' => [
        'web',
        MrTolouei\ServiceHealth\Http\Middleware\Authorize::class,
    ],
],
```

Controls route URLs and middleware.

#### history\_limit

[](#history_limit)

```
'history_limit' => env('SERVICE_HEALTH_LIMIT_HISTORY', 20),
```

Used by the dashboard for limiting displayed history items.

#### refresh\_interval

[](#refresh_interval)

```
'refresh_interval' => env('SERVICE_HEALTH_REFRESH_INTERVAL', 3000),
```

Dashboard refresh interval in milliseconds.

Example:

- 3000 = every 3 seconds
- 10000 = every 10 seconds

#### expose\_exception\_messages

[](#expose_exception_messages)

```
'expose_exception_messages' => env('SERVICE_HEALTH_EXPOSE_EXCEPTION_MESSAGES', true),
```

Controls whether raw exception messages should be shown in results.

- `true`: actual exception messages are exposed
- `false`: generic safe messages are returned

For production environments, you may prefer setting this to `false`.

### Monitor Configuration

[](#monitor-configuration)

Each monitor has a structure similar to this:

```
'monitor_name' => [
    'enabled' => true,
    'inspector' => SomeInspector::class,
    'slow_threshold' => 20,
    'connections' => [
    ...
    ],
],
```

#### Common fields

[](#common-fields)

`enabled`

Whether this monitor is active.

`inspector`

The class responsible for performing the health check.

`slow_threshold`

If the check completes successfully but takes longer than this threshold (ms), the result becomes degraded instead of healthy.

`connections`

The list of things to inspect.

> For some inspectors, each item is a string connection name.

> For HttpInspector, each item is a full config array.

---

Usage Examples
--------------

[](#usage-examples)

### Monitoring Multiple Database Connections

[](#monitoring-multiple-database-connections)

```
'database' => [
    'enabled' => true,
    'inspector' => MrTolouei\ServiceHealth\Inspectors\DatabaseInspector::class,
    'slow_threshold' => 50,
    'connections' => [
        'mysql',
        'analytics',
        'tenant',
    ],
],
```

This will create separate health results for each configured database connection.

### Monitoring External APIs

[](#monitoring-external-apis)

```
'http' => [
    'enabled' => true,
    'inspector' => MrTolouei\ServiceHealth\Inspectors\HttpInspector::class,
    'connections' => [
        [
            'name' => 'GitHub API',
            'endpoint' => 'https://api.github.com',
            'method' => 'GET',
            'expected_status' => 200,
            'headers' => [
                'Accept' => 'application/json',
                'User-Agent' => 'LaravelServiceHealth',
            ],
            'timeout' => 5,
            'slow_threshold' => 2000,
        ],
        [
            'name' => 'Payment Gateway Health',
            'endpoint' => 'https://payments.example.com/health',
            'method' => 'GET',
            'expected_status' => 200,
            'auth' => [
                'type' => 'bearer',
                'token' => env('PAYMENT_GATEWAY_TOKEN'),
            ],
            'timeout' => 5,
            'slow_threshold' => 1000,
        ],
    ],
],
```

### Monitoring Internal Services with Auth

[](#monitoring-internal-services-with-auth)

```
'http' => [
    'enabled' => true,
    'inspector' => MrTolouei\ServiceHealth\Inspectors\HttpInspector::class,
    'connections' => [
        [
            'name' => 'Internal Admin API',
            'endpoint' => 'https://internal.example.com/api/health',
            'method' => 'GET',
            'expected_status' => 200,
            'headers' => [
                'Accept' => 'application/json',
            ],
            'auth' => [
                'type' => 'basic',
                'username' => env('INTERNAL_API_USER'),
                'password' => env('INTERNAL_API_PASSWORD'),
            ],
            'timeout' => 3,
            'slow_threshold' => 800,
        ],
    ],
],
```

---

Dashboard
---------

[](#dashboard)

The dashboard route renders a Blade view:

```
return view('service-health::dashboard');
```

By default, it is available at:

```
/service-health

```

This dashboard is intended to give a quick visual overview of:

- service statuses
- degraded/failed services
- timings
- refresh-based updates

You may publish and customize the view if needed.

---

JSON API
--------

[](#json-api)

The API endpoint returns a structured JSON response including:

- checked\_at
- summary
- services

Default route:

```
/service-health-api

```

### Summary keys

[](#summary-keys)

- total
- healthy
- degraded
- failed
- average\_duration
- slowest\_service
- slowest\_duration
- overall\_status

### Service item keys

[](#service-item-keys)

- name
- status
- is\_healthy
- is\_degraded
- is\_failed
- is\_up
- message
- duration
- metadata
- type
- connection

---

Artisan Command
---------------

[](#artisan-command)

Run checks via CLI:

```
  php artisan service-health:check
```

### JSON output

[](#json-output)

```
  php artisan service-health:check --json
```

### Behavior

[](#behavior)

- Prints a table of all services
- Returns failure exit code if any service has failed
- Returns success if all services are either healthy or degraded

This makes it useful for:

- deployment pipelines
- cron jobs
- uptime scripts
- container health checks
- infrastructure monitoring

---

Authorization
-------------

[](#authorization)

The package uses this middleware by default:

```
MrTolouei\ServiceHealth\Http\Middleware\Authorize::class
```

That middleware delegates authorization to:

```
ServiceHealth::check($request)
```

By default, if no custom auth callback is defined, access is only allowed in the `local` environment.

To customize this, publish the provider stub:

```
  php artisan vendor:publish --tag=service-health-provider
```

Then define your gate in the generated provider.

Example:

```