happenv-com/laravel-true-modular-health

Module-scoped health checks for laravel-true-modular: declare checks per module, aggregate runtime + architecture health via Spatie Laravel Health and module:doctor.

v1.0.0 2026-06-28 05:54 UTC

Requires

• php: ^8.3
• happenv-com/laravel-true-modular: ^1.0
• spatie/laravel-health: ^1.0

Requires (Dev)

• larastan/larastan: ^3.10
• laravel/pint: ^1.29
• orchestra/testbench: ^11.1
• pestphp/pest: ^4.0

MIT

• webard

• health
• laravel
• modular-monolith
• spatie-health

README

A companion to laravel-true-modular that lets each module declare its own health checks, registers them into Spatie Laravel Health, and adds a module:doctor command that aggregates runtime health (the module checks) with architecture health (dependency-cycle detection) in one report.

Why

The core package gives every module a persistent capability record (the module manifest). This package reads that manifest, so health checks live next to the module that owns them instead of in one central list:

$module
    ->hasRoutes()
    ->hasHealthChecks([
        InventoryLedgerCheck::class,
        ReservationIntegrityCheck::class,
    ]);

InventoryLedgerCheck is a plain Spatie Check (Spatie\Health\Checks\Check). The core stores only the class name; this package validates and instantiates it.

Install

composer require happenv-com/laravel-true-modular-health

It auto-discovers. On boot it merges every module's declared checks into Spatie Health (preserving any checks you registered yourself), so your existing health:check command, scheduled run, and dashboard include them automatically.

module:doctor

php artisan module:doctor                 # runtime + architecture
php artisan module:doctor --module=inventory   # runtime checks for one module (architecture still runs)
php artisan module:doctor --json          # machine-readable

The command exits non-zero when any check is failed or crashed, so it doubles as a CI gate. JSON output carries a stable envelope:

{
    "schema": { "name": "doctor", "version": 1 },
    "summary": { "ok": 2, "warning": 0, "failed": 1, "crashed": 0, "skipped": 0 },
    "modules": {
        "inventory": [
            { "check": "InventoryLedger", "status": "failed", "message": "..." }
        ],
        "architecture": [
            { "check": "Cycle", "status": "ok", "message": null }
        ]
    }
}

Architecture checks

Cycle (Happenv\LaravelTrueModular\Health\Architecture\CycleCheck) fails when the module dependency graph contains a circular dependency. It reuses the core's own topological sort, so it sees the same edges the framework uses to order providers.

License

MIT.