README

Laravel Status Page (manggala/laravel-status-page) is a production-ready, self-hosted application health diagnostics and status page package for Laravel applications powered by Inertia.js & React.

💡 Why Laravel Status Page?

Commercial status page services (such as Statuspage.io, Better Uptime, or Datadog) cost hundreds of dollars per month for basic public status pages and alert routing. Existing open-source Laravel packages (like Spatie's laravel-health) focus strictly on backend CLI outputs or simple Blade templates.

Laravel Status Page provides a complete, self-hosted alternative:

Zero Monthly Subscription Fees: Hosted 100% natively inside your application's infrastructure.
Modern Inertia React Public Status Page (/status): Beautiful, high-contrast public status UI with interactive 90-day uptime bars.
Multi-Channel Alert Dispatcher: Automatic incident notifications dispatched to Telegram, Slack, and Discord.
Plug & Play Diagnostic Probes: Modular health checks for Database, Redis, Queue Workers, Storage Disks, SSL Certificates, and External APIs.

🌟 Key Features

Self-Hosted Public Status View (/status): Beautiful, responsive status page showing overall system health (All Systems Operational, Degraded Performance, Partial Outage, Major Outage).
Modular Diagnostic Probe Suite: Built-in health check drivers for:
- 🗄️ Database Connection & Latency
- ⚡ Redis Cache & Memory Utilization
- 🔄 Queue Worker Backlog & Heartbeat
- 💾 Storage Disk Capacity & Write Permissions
- 🔒 SSL Certificate Expiration Warnings
- 🌐 External HTTP Endpoint Ping & Response Codes
Incident Timeline & Maintenance Management: Admin management controls for creating incident logs and announcing scheduled maintenance windows.
Automated Multi-Channel Webhook Notifications: Instant alert dispatching to Telegram, Slack, Discord, or Email with 15-minute cooldown throttling to prevent notification spam.
Fault Isolation Guarantee: A failure in one probe (e.g. Redis crash) will NEVER crash the diagnostic runner or application.
Manggala Ecosystem Interoperability: Configurable via laravel-settings and embeddable as visual widgets into laravel-dashboard-builder.

📦 Installation

Install the package via Composer:

composer require manggala/laravel-status-page

Run the package installation wizard to publish configuration, database migrations, and Inertia React component views:

php artisan status-page:install

Run the database migrations:

php artisan migrate

Optionally publish resources manually:

# Publish configuration file
php artisan status-page:publish --tag=config

# Publish database migrations
php artisan status-page:publish --tag=migrations

# Publish React page views
php artisan status-page:publish --tag=views

🚀 Quick Start & Probe Usage

1. Registering Custom Diagnostic Probes

use Manggala\StatusPage\Facades\StatusPage;
use Manggala\StatusPage\Probes\DatabaseProbe;
use Manggala\StatusPage\Probes\RedisCacheProbe;
use Manggala\StatusPage\Probes\QueueWorkerProbe;
use Manggala\StatusPage\Probes\StorageDiskProbe;
use Manggala\StatusPage\Probes\SslCertificateProbe;
use Manggala\StatusPage\Probes\HttpEndpointProbe;

public function boot(): void
{
    StatusPage::register([
        DatabaseProbe::make()->maxLatencyMs(250),
        RedisCacheProbe::make()->maxMemoryPercent(90),
        QueueWorkerProbe::make()->maxBacklogJobs(500),
        StorageDiskProbe::make()->maxDiskUsagePercent(90),
        SslCertificateProbe::forDomain('example.com')->warnIfExpiresWithinDays(14),
        HttpEndpointProbe::make('Payment Gateway API')->url('https://api.stripe.com/v1/health'),
    ]);
}

2. Writing a Custom Health Probe

Implement ProbeInterface to monitor custom microservices or third-party APIs:

namespace App\Probes;

use Manggala\StatusPage\Contracts\ProbeInterface;
use Manggala\StatusPage\Core\ProbeResult;

class PaymentGatewayProbe implements ProbeInterface
{
    public function name(): string
    {
        return 'Payment Gateway Service';
    }

    public function check(): ProbeResult
    {
        $startTime = microtime(true);
        $response = Http::get('https://payment-gateway.test/ping');
        $latencyMs = (int) ((microtime(true) - $startTime) * 1000);

        if ($response->failed()) {
            return ProbeResult::failing($this->name(), $latencyMs, 'Gateway returned HTTP ' . $response->status());
        }

        return ProbeResult::healthy($this->name(), $latencyMs);
    }
}

3. Scheduling Background Diagnostics

Add the diagnostic check command to your application scheduler in routes/console.php:

use Illuminate\Support\Facades\Schedule;

// Run health checks every 5 minutes
Schedule::command('status-page:check')->everyFiveMinutes();

// Prune historical check logs older than 30 days
Schedule::command('status-page:prune --days=30')->daily();

🔔 Multi-Channel Alert Configuration

Configure alert notification channels in config/status-page.php:

return [

    /*
    |--------------------------------------------------------------------------
    | Alert Notification Channels
    |--------------------------------------------------------------------------
    */
    'notifications' => [
        'enabled' => env('STATUS_PAGE_ALERTS_ENABLED', true),
        
        // Cooldown period per probe failure to prevent alert spamming
        'cooldown_minutes' => 15,

        'channels' => [
            'telegram' => [
                'bot_token' => env('TELEGRAM_BOT_TOKEN'),
                'chat_id' => env('TELEGRAM_CHAT_ID'),
            ],

            'slack' => [
                'webhook_url' => env('SLACK_STATUS_WEBHOOK_URL'),
            ],

            'discord' => [
                'webhook_url' => env('DISCORD_STATUS_WEBHOOK_URL'),
            ],
        ],
    ],

];

⚙️ Configuration Reference

The published configuration file (config/status-page.php) controls route endpoints, diagnostic thresholds, and retention policies:

return [

    /*
    |--------------------------------------------------------------------------
    | Route & Access Settings
    |--------------------------------------------------------------------------
    */
    'route' => [
        'path' => '/status',
        'middleware' => ['web'],
    ],

    /*
    |--------------------------------------------------------------------------
    | Historical Uptime Retention Policy
    |--------------------------------------------------------------------------
    */
    'retention' => [
        'history_days' => 90, // Displayed in 90-day history bar UI
        'prune_after_days' => 30, // Database log pruning threshold
    ],

];

🛠️ Artisan Commands

Command	Description
`php artisan status-page:install`	Interactive wizard to publish config, migrations, and Inertia React component views.
`php artisan status-page:check`	Run all registered health probes on demand and record results.
`php artisan status-page:prune --days=30`	Prune historical check logs older than X days to keep database size optimal.
`php artisan status-page:doctor`	Run diagnostic health check on package setup, database tables, and webhooks.

🔗 Ecosystem Interoperability

Laravel Status Page integrates seamlessly into the Manggala Ecosystem:

manggala/laravel-manifest (laravel-settings): Notification webhooks (Telegram Bot Token, Slack Webhook URL) and alert thresholds can be managed dynamically via setting schemas.
manggala/laravel-dashboard-builder: Embed real-time Server Health Cards and Uptime Gauges directly into visual custom dashboards.
manggala/laravel-spotlight: Type "Status" or "Health Check" in Cmd+K to open diagnostic status views instantly.

🧪 Testing & Code Quality

Run the Pest PHP test suite:

vendor/bin/pest

Format code styling with Laravel Pint:

vendor/bin/pint

Run static analysis with Larastan / PHPStan (Level 8):

vendor/bin/phpstan analyse

📜 License

The MIT License (MIT). Please see LICENSE for more information.

manggala / laravel-status-page

Maintainers

Package info

Statistics

Security