README

Eloquent Guard is a lightweight, production-ready runtime performance monitor for Laravel. It detects N+1 queries and slow database operations as they happen, helping you keep your application fast and efficient.

✨ Features

• N+1 Query Detection: Automatically detects repeated queries within a single request.
• Slow Query Monitor: Alerts you when a query exceeds your defined time limit.
• Laravel Pulse Integration: Beautiful custom dashboard card to visualize alerts.
• Smart Backtrace: Pinpoints the exact file and line of code causing the issue (skips vendor files).
• Multi-channel Reporting: Built-in support for Log, Slack, Telegram, and Sentry.
• Zero Configuration: Works out of the box with sensible defaults.

📢 Multi-Channel Reporting

Stay informed where your team already works. All alerts include a Smart Backtrace that points directly to your code, skipping the vendor/ noise.

Channel	Preview
Slack
Telegram
Sentry
Laravel Logs	[2026-03-09 21:27:16] local.WARNING: Eloquent Guard: N+1 detected! {"sql":"select * from users where users.id = ? limit 1","count":5,"source":"/var/www/html/routes/web.php:9"} [2026-03-09 21:27:17] local.CRITICAL: Eloquent Guard: Slow Query! {"sql":"SELECT SLEEP(1)","duration":"1000.47ms","source":"/var/www/html/routes/web.php:13"}

🚀 Installation

You can install the package via composer:

composer require maxis/laravel-eloquent-guard

Usage

Publish Configuration

Publish the configuration file to customize thresholds, ignored tables, and active reporters:

php artisan vendor:publish --provider="Maxis\EloquentGuard\EloquentGuardServiceProvider" --tag="config"

Configure Environment

Add your webhook URLs or bot tokens to your .env file for instant alerts:

ELOQUENT_GUARD_ENABLED=true
ELOQUENT_GUARD_SLACK_WEBHOOK=https://hooks.slack.com...
ELOQUENT_GUARD_TELEGRAM_TOKEN=your-bot-token
ELOQUENT_GUARD_TELEGRAM_CHAT_ID=your-chat-id

Important

Queue Worker Required: To ensure your application's performance is not affected, reporting (Slack, Telegram, Sentry) is handled via Laravel's queue system. Make sure your queue worker is running (php artisan queue:work) to receive alerts.

⚙️ Configuration

Once published, you can find the settings in config/eloquent-guard.php.

Thresholds & Limits

Customize what constitutes a performance issue for your specific application:

'limits' => [
    'n_plus_one_threshold' => 5,   // Alert after 5 identical queries in one request
    'query_duration_ms' => 500,    // Alert if a single query takes more than 500ms
],

Reporters

Enable or disable notification channels by adding/removing classes from the reporters array:

'reporters' => [
    \Maxis\EloquentGuard\Reporters\LogReporter::class,      // Standard Laravel Logs
    \Maxis\EloquentGuard\Reporters\SlackReporter::class,    // Slack Webhooks (Queue Worker Required)
    \Maxis\EloquentGuard\Reporters\TelegramReporter::class, // Telegram Bot API (Queue Worker Required)
    \Maxis\EloquentGuard\Reporters\SentryReporter::class,   // Sentry Issue Tracking (Queue Worker Required)
],

Ignored Tables

Prevent noise from system tables (like sessions or cache):

'except_tables' => ['sessions', 'cache', 'pulse_entries', 'jobs', 'migrations'],

📊 Laravel Pulse Integration

Eloquent Guard comes with a dedicated Laravel Pulse card to visualize N+1 and Slow Query trends directly in your dashboard.

Add the Card to Dashboard

Include the Livewire component in your resources/views/vendor/pulse/dashboard.blade.php:

<x-pulse>
    <!-- Display Eloquent Guard Alerts -->
    <livewire:maxis.eloquent-guard cols="4" />

    <!-- Existing Pulse cards... -->
</x-pulse>

🧪 Testing

The package is fully tested with PHPUnit. If you are developing locally or using Laravel Sail, run the test suite with:

# Using Laravel Sail
sail php ./packages/maxis/eloquent-guard/vendor/bin/phpunit -c ./packages/maxis/eloquent-guard/phpunit.xml

# Or standard PHPUnit from the package directory
./vendor/bin/phpunit

🤝 Contributing

Contributions make the open-source community amazing!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

📄 License

Distributed under the MIT License. See LICENSE.md for more information.