README

Arabic Version (النسخة العربية)

Real-time error monitoring, intelligent alerts, and traffic surveillance for Laravel applications.

PulseAlert is a lightweight, zero-configuration package designed to keep you informed about your application's health. It goes beyond simple logging by classifying errors, sending instant Telegram notifications for critical issues, and providing daily summaries.

✨ Features

• Intelligent Priority Engine: Automatically classifies exceptions (CRITICAL, HIGH, MEDIUM, LOW).
• Telegram Instant Alerts: Receive 🔴 Critical and 🟠 High priority alerts directly on Telegram.
• Smart Rate Limiting: Prevents alert spam by silencing duplicate errors for 10 minutes.
• Traffic Surveillance: Middleware to detect and notify about suspicious request volume from single IPs.
• Daily Error Digest: Beautifully formatted email summaries sorted by importance.
• Data Sanitization: Automatically scrubs sensitive data (passwords, tokens) from stack traces.

🚀 Installation

Step 1 — Install via Composer

composer require mohamedsamy902/laravel-pulse-alert

Step 2 — Publish Config & Migrations

php artisan vendor:publish --tag=pulse-alert-config
php artisan vendor:publish --tag=pulse-alert-migrations

Step 3 — Run Migrations

php artisan migrate

📋 Configuration

Environment Variables

Add these keys to your .env file:

Registering the Logger (Laravel 11/12)

In your bootstrap/app.php, register the PulseAlert logger within the withExceptions block:

use MohamedSamy902\PulseAlert\Services\ErrorLogger;

// ...
->withExceptions(function (Exceptions $exceptions) {
    app(ErrorLogger::class)->register($exceptions);
})

Scheduling the Daily Report

In your routes/console.php, schedule the report to run daily:

use Illuminate\Support\Facades\Schedule;

Schedule::command('pulse-alert:daily-report')->dailyAt('08:00');

📖 Usage

Automatic Traffic Surveillance

The package automatically registers its rate-limiting middleware globally. All requests (Web, API, Dashboard) are monitored by default using the settings in your config file.

Manual Logging

You can manually log errors with a specific priority if needed:

use MohamedSamy902\PulseAlert\Services\ErrorLogger;

try {
    // ... code
} catch (\Exception $e) {
    app(ErrorLogger::class)->log($e, 'CRITICAL');
}

🎯 Priority Classification Logic

• CRITICAL: Database errors, 500 status codes, or severe engine errors. (Instant Alert 🔴)
• HIGH: Keywords like "payment", "unauthorized", "auth", or "token" detected in message. (Instant Alert 🟠)
• MEDIUM: General exceptions that don't match critical/high criteria. (Daily Report only)
• LOW: Minor issues or manually logged low-priority events. (Daily Report only)

🧪 Testing

composer test

📄 License

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