prmgtk/laravel-monitor

Report errors from any Laravel site to the prmgtk error-monitoring platform. English | العربية

English

What it does

• Captures every reportable exception automatically (Laravel's own dontReport list is respected, normal logging is untouched), including fatal errors and failed queue jobs.
• Groups, de-duplicates and throttles reports, scrubs secrets, and sends them to prmgtk without slowing the site (after the response, 1.5 s timeout).
• Never breaks your app: every code path is wrapped, with a re-entrancy guard, a local circuit breaker and graceful degradation when the cache or the network is down.

Requirements

PHP 8.1+ and Laravel 10, 11, 12 or 13.

Installation

Option 1 - Packagist (once published)

composer require prmgtk/laravel-monitor

Option 2 - GitHub (VCS repository) - add to the host app's composer.json:

{
    "repositories": [
        { "type": "vcs", "url": "https://github.com/WaelMz/prmgtk-laravel-monitor" }
    ],
    "require": {
        "prmgtk/laravel-monitor": "^1.0"
    }
}

then run composer update prmgtk/laravel-monitor.

Option 3 - local path

{
    "repositories": [
        { "type": "path", "url": "../laravel-monitor", "options": { "symlink": true } }
    ],
    "require": {
        "prmgtk/laravel-monitor": "*"
    }
}

The service provider and the PrmgtkMonitor facade alias are auto-discovered.

Setup

php artisan prmgtk-monitor:install   # publishes config, adds the keys to .env and .env.example

PRMGTK_MONITOR_KEY=prm_xxxxxxxxxxxxxxxx
PRMGTK_MONITOR_URL=https://prmgtk.com

The secret site key is provided to you by prmgtk. Keep it only in .env and never commit it.

By default only the production environment reports. To test from another environment set PRMGTK_MONITOR_ENVIRONMENTS=production,staging (or leave it empty for all), then verify:

php artisan prmgtk-monitor:test

It checks the config, pings the platform and sends a clearly labelled "prmgtk monitor test exception". It works even if the current environment is not in the list (a notice is shown; --force hides it).

Configuration reference (config/prmgtk-monitor.php)

Hooks accept a Closure, an invokable class name, or Class@method. Closures cannot be used if you run config:cache; use a class instead.

// config/prmgtk-monitor.php
'context' => App\Monitoring\ExtraContext::class,      // fn (?Throwable $e): array
'before_send' => App\Monitoring\BeforeSend::class,    // fn (array $payload, ?Throwable $e): ?array

Manual capture

use Prmgtk\Monitor\Facades\PrmgtkMonitor;

try {
    $gateway->charge($order);
} catch (Throwable $e) {
    PrmgtkMonitor::captureException($e, ['order_id' => $order->id]);          // level auto-detected
    PrmgtkMonitor::captureException($e, ['order_id' => $order->id], 'warning');
}

PrmgtkMonitor::captureMessage('Payment gateway is slow', 'warning', ['ms' => 3200]);
$ok = PrmgtkMonitor::ping();   // array (decoded response) or false

Manual captures bypass dont_report / ignore_http_4xx but still honour the environment, level, throttle and circuit-breaker rules.

Log channel

// config/logging.php
'channels' => [
    'prmgtk' => ['driver' => 'prmgtk', 'level' => 'error'],
    'stack'  => ['driver' => 'stack', 'channels' => ['daily', 'prmgtk']],
],

Records that carry an exception in their context use it. Exceptions already captured by the handler are not sent twice.

Queue mode

PRMGTK_MONITOR_QUEUE_ENABLED=true
PRMGTK_MONITOR_QUEUE_CONNECTION=redis
PRMGTK_MONITOR_QUEUE=monitoring

Run a worker for that queue. The job never fails loudly and never retries.

Privacy and scrubbing

• Request body, query, headers and context are scrubbed recursively: keys containing password, token, secret, api_key, authorization, cookie, card, cvv, ... become [filtered].
• Authorization, Cookie, X-CSRF-* and X-XSRF-* headers are never sent. Uploaded files are replaced by [file: name, size].
• Only the user's id and email are sent. File paths are relative to base_path(); the server layout is not sent, only a short hash (runtime.base_path_hash).
• Large values are truncated and the whole payload is kept under 250 KB. The platform scrubs again on receipt and stores IPs only as a hash.
• Disable parts with capture.request_body, capture.headers, capture.user.

Troubleshooting

• Nothing arrives - run php artisan prmgtk-monitor:test. Check PRMGTK_MONITOR_ENVIRONMENTS (default production only), min_level, the throttle window, and that the exception is not in dontReport. If the exception class defines its own report() method returning anything but false, Laravel skips reportable callbacks.
• 401 - the key is wrong or no longer valid; contact prmgtk for a new one. One warning per hour is written to your log: prmgtk monitor: invalid key.
• 429 - rate limited (120 requests/minute per site). Sending pauses for the Retry-After period.
• config:cache - after changing .env run php artisan config:clear / config:cache; closures in the config file break config:cache.
• Queue workers - restart workers (queue:restart) after changing config.

Uninstall

composer remove prmgtk/laravel-monitor
rm config/prmgtk-monitor.php

Remove the PRMGTK_MONITOR_* keys from .env and any prmgtk channel from config/logging.php.

Testing

composer install
vendor/bin/phpunit
# optional end-to-end run against a real receiver
PRMGTK_E2E_KEY=prm_... PRMGTK_E2E_URL=http://localhost:8000 vendor/bin/phpunit --group e2e

License

MIT

العربية

ماذا تفعل الحزمة؟

ترسل أخطاء أي موقع لارافيل تلقائياً إلى منصة prmgtk لمراقبة الأخطاء، فتظهر في صندوق الأخطاء مع إشعار للفريق. تلتقط الاستثناءات غير المعالجة والأخطاء القاتلة وفشل مهام الطابور، وتحترم قائمة dontReport في تطبيقك، ولا تغيّر سلوك السجلات الاعتيادي. لا تؤثر على سرعة الموقع: الإرسال يتم بعد إرسال الاستجابة بمهلة 1.5 ثانية، وكل مسار محمي بحيث لا تكسر الحزمة موقعك أبداً.

المتطلبات

PHP 8.1 أو أحدث، ولارافيل 10 أو 11 أو 12 أو 13.

التركيب

1. Packagist (بعد النشر): composer require prmgtk/laravel-monitor
2. مستودع GitHub: أضف في composer.json للموقع قسم repositories بنوع vcs ورابط المستودع، ثم composer require prmgtk/laravel-monitor:^1.0.
3. مسار محلي: أضف مستودعاً بنوع path يشير إلى مجلد الحزمة (انظر الأمثلة بالإنجليزية أعلاه).

ثم نفّذ:

php artisan prmgtk-monitor:install

وأضف المفتاح في .env:

PRMGTK_MONITOR_KEY=prm_xxxxxxxxxxxxxxxx
PRMGTK_MONITOR_URL=https://prmgtk.com

المفتاح السري

تستلم المفتاح السري الخاص بموقعك من إدارة برمجتك. احفظه في ملف .env فقط ولا ترفعه على Git.

الاختبار

php artisan prmgtk-monitor:test

يتحقق من الإعدادات ويختبر الاتصال ثم يرسل استثناءً تجريبياً بعنوان "prmgtk monitor test exception". يعمل حتى لو كانت البيئة الحالية غير مفعّلة (مع تنبيه، والخيار --force يخفيه).

أهم الإعدادات

• PRMGTK_MONITOR_ENVIRONMENTS: البيئات التي تُرسل الأخطاء (الافتراضي production؛ اتركه فارغاً لكل البيئات).
• PRMGTK_MONITOR_THROTTLE_SECONDS: الخطأ المتطابق يُرسل مرة واحدة كل 60 ثانية لكل خادم.
• PRMGTK_MONITOR_MAX_PER_MINUTE: قاطع محلي (30 تقريراً في الدقيقة).
• PRMGTK_MONITOR_QUEUE_ENABLED: إرسال عبر الطابور بدل الإرسال المباشر.

الإرسال اليدوي

PrmgtkMonitor::captureException($e, ['order_id' => 15]);
PrmgtkMonitor::captureMessage('بطء في بوابة الدفع', 'warning');

قناة السجلات

أضف في config/logging.php: 'prmgtk' => ['driver' => 'prmgtk', 'level' => 'error'] ثم أضفها إلى قناة stack.

الخصوصية

كلمات المرور والرموز والكوكيز وبيانات البطاقات تُستبدل بـ [filtered] بشكل متكرر في الطلب والسياق. لا تُرسل ترويسات Authorization وCookie وCSRF أبداً، وتُستبدل الملفات المرفوعة بوصف نصي، ولا يُرسل من المستخدم إلا المعرّف والبريد، والمسارات نسبية لمجلد المشروع.

حل المشاكل

• لا تصل أخطاء: شغّل php artisan prmgtk-monitor:test، وتأكد من البيئة (production افتراضياً) والمستوى الأدنى، ومن أن الإعدادات غير مخزّنة قديمة (php artisan config:clear).
• 401: المفتاح خاطئ أو أُعيد إنشاؤه؛ يُكتب تحذير واحد في السجل كل ساعة.
• 429: تجاوز حد المعدل؛ يتوقف الإرسال تلقائياً للمدة المطلوبة.

إلغاء التركيب

composer remove prmgtk/laravel-monitor

ثم احذف ملف config/prmgtk-monitor.php ومفاتيح PRMGTK_MONITOR_* من .env.