webmavens/debug-monitor

Laravel debug / data rule monitoring package

0.1 2026-06-23 10:00 UTC

Requires

• php: ^8.2
• illuminate/console: ^10.0 || ^11.0 || ^12.0
• illuminate/database: ^10.0 || ^11.0 || ^12.0
• illuminate/http: ^10.0 || ^11.0 || ^12.0
• illuminate/notifications: ^10.0 || ^11.0 || ^12.0
• illuminate/routing: ^10.0 || ^11.0 || ^12.0
• illuminate/support: ^10.0 || ^11.0 || ^12.0
• illuminate/view: ^10.0 || ^11.0 || ^12.0

Requires (Dev)

• pestphp/pest: ^3.0
• phpunit/phpunit: ^11.0

MIT

• webmavens

Published on Packagist.org on 2026-06-23 10:02 UTC

README

A lightweight Laravel package that helps developers and administrators automatically run SQL-based health checks, detect data anomalies, and get notified when something goes wrong.

🚀 Features

• 🔍 Define SQL-based debug rules directly from the web UI
• 📁 Ship version-controlled rule files and sync them into the database (migration-style)
• 🕒 Run rules automatically via scheduler or manually using an Artisan command
• 📊 Store and view detailed execution logs
• 🧹 Automatically clean old logs (configurable retention)
• ✉️ Send email notifications for failed rules
• ⚙️ Supports SQLite and MySQL
• 🔒 Secure access with a local-by-default gate and optional email allowlist
• 🧱 Easy to extend and customize

📦 Installation

Require the package via Composer:

composer require webmavens/debug-monitor

OR

composer require webmavens/debug-monitor:@dev

⚙️ Publishing Configuration, Views & Provider

Publish configuration:

php artisan vendor:publish --provider="Webmavens\DebugMonitor\DebugMonitorServiceProvider" --tag=config

Publish views:

php artisan vendor:publish --provider="Webmavens\DebugMonitor\DebugMonitorServiceProvider" --tag=views

Publish migrations

php artisan vendor:publish --provider="Webmavens\DebugMonitor\DebugMonitorServiceProvider" --tag=migrations

Run the migrations:

php artisan migrate

🔑 Authentication

By default, Debug Monitor is accessible in the local environment only.

Customizing Access

Set one or both of these environment values:

DEBUG_MONITOR_ALLOW_IN_LOCAL=true
DEBUG_MONITOR_ALLOWED_EMAILS=[e-mail],[e-mail]

• DEBUG_MONITOR_ALLOW_IN_LOCAL=true keeps the dashboard open in local.
• DEBUG_MONITOR_ALLOWED_EMAILS is a comma-separated allowlist used when APP_ENV is not local.

You do not need to publish or register a custom provider for the default access behavior.

🧭 Usage

🖥️ Web Dashboard

Visit /debug-monitor/rules to:

• View all rules
• Create new rules
• Edit or delete rules
• Suppress temporarily
• Review logs

⚡ Run Scheduler

php artisan schedule:work

⚡ Run Manually

Run all active rules manually via Artisan:

php artisan debug-monitor:run

🧹 Log Cleanup (Automatic Maintenance)

Old logs can be automatically deleted using the built-in cleanup command.

Run Manually:

php artisan debug-monitor:clean
or
php artisan debug-monitor:clean --days=7

Configure Retention Period:

In config/debug-monitor.php:

'log_retention_days' => env('DEBUG_MONITOR_LOG_RETENTION_DAYS', 30),

📁 Version-Controlled Rule Files (Sync to DB)

Rules can also live as version-controlled JSON files that are synced into the database. Rules always execute from the database — files are never run directly. Each file stays linked to its database rule (with a content checksum), so the two can be kept in step:

• Sync applies new files and updates changed files (detected by checksum).
• If a database rule with the same name already exists and isn't linked to the file, the file is skipped (the database wins).
• Editing a linked rule in the UI rewrites its file on disk.
• Exporting a UI-created rule turns it into a linked file.
• Deleting a linked rule removes its file too.

Publish the rules directory (creates debug-monitor-rules/ with an example):

php artisan vendor:publish --provider="Webmavens\DebugMonitor\DebugMonitorServiceProvider" --tag=debug-monitor-rules

You can author files two ways: write them by hand, or build a rule in the UI and export it (the "Export" action on a rule, or php artisan debug-monitor:export).

A rule file, e.g. debug-monitor-rules/missing-user-emails.json:

{
    "name": "Users missing email",
    "sql_query": "SELECT * FROM users WHERE email IS NULL",
    "frequency_minutes": 15,
    "importance_level": "high",
    "expected_rows_operator": "=",
    "expected_rows": 0,
    "expected_json": null,
    "notification_level": "default",
    "status": "active"
}

Import pending files into the database using the "Sync from files" button on /debug-monitor/rules (it shows how many files are pending), or via Artisan (ideal for deploy pipelines):

php artisan debug-monitor:sync      # apply new + changed files
php artisan debug-monitor:export    # export DB rules to files (--id=1 --id=2 for specific rules)

The directory is configurable in config/debug-monitor.php:

'rules_path' => env('DEBUG_MONITOR_RULES_PATH', base_path('debug-monitor-rules')),

🛡️ Query Safety & Reliability

Rules run against your database, so execution is guarded for safety and to stay reliable on large / complex queries:

• Read-only only — a rule must be a single SELECT / WITH / SHOW / EXPLAIN statement. Anything that could mutate data or stack a second statement is rejected.
• Streamed, not buffered — results are streamed and counted, so a query returning millions of rows won't exhaust memory. Only a bounded sample (max_rows) is kept for logs and JSON matching; the row count is always exact.
• Per-statement timeout — a runaway query aborts instead of hanging the run (MySQL/MariaDB and PostgreSQL).
• Non-overlapping schedule — a slow run won't stack on top of the next one.

Configure via .env / config/debug-monitor.php:

DEBUG_MONITOR_READ_ONLY=true   # enforce read-only single-statement rules
DEBUG_MONITOR_QUERY_TIMEOUT=30 # per-query timeout in seconds (0 = off)
DEBUG_MONITOR_MAX_ROWS=1000    # cap on rows sampled/stored per run

Alerts are queued (ShouldQueue), so run a queue worker for them to send: php artisan queue:work.

🧰 Example Debug Rule

You can define rules such as:

Name	SQL Query	Frequency	Expected Rows
Missing Users	SELECT * FROM users WHERE email IS NULL	15 minutes	0
Stuck Orders	SELECT * FROM orders WHERE status='pending' AND created_at < NOW() - INTERVAL 2 HOUR	10 minutes	0

When a rule fails (unexpected result), the system:

• Logs it in the debug_rule_logs table
• Updates its last run time
• Sends an alert (if notifications are enabled)

📬 Notifications

Set up your mail credentials in .env and configure the email notification in your config/debug-monitor.php file:

'notify_email' => env('DEBUG_MONITOR_NOTIFY_EMAIL', '[e-mail]'),

Failed rules will trigger an email with detailed information.

Support

For any issues, feel free to create an issue in the GitHub repository.

🤝 Contributing

Pull requests are welcome! If you’d like to improve or extend this package, please fork the repo and create a PR.

🧠 License

This package is open-source software licensed under the MIT license.