Monolog PHP: الطرق، الأمثلة، التثبيت

ما هو Monolog ولماذا هو مطلوب؟

\n\n

Monolog هي مكتبة قياسية لتسجيل السجلات (logging) في PHP. توفر مجموعة أدوات مرنة وقوية لتسجيل السجلات في قنوات مختلفة (ملفات، قواعد بيانات، بريد إلكتروني، سجل النظام، خدمات خارجية، إلخ). Monolog هو المعيار الفعلي لتطبيقات PHP، خاصة في بيئة Symfony و Laravel وأطر العمل الحديثة الأخرى.

\n\n

لماذا نحتاج هذه المكتبة؟ في أي تطبيق، من الضروري تتبع الأحداث: الأخطاء، التحذيرات، الرسائل الإعلامية، معلومات التصحيح. يتيح لك Monolog:

مركزية التسجيل — كتابة السجلات بتنسيق واحد ومن أي مكان في التطبيق.
تكوين القنوات بمرونة — إرسال الأخطاء الحرجة إلى Telegram/Slack، والرسائل الإعلامية إلى ملف.
تنسيق الرسائل — إضافة التاريخ، المستوى، السياق، مكدس الاستدعاءات.
تصفية السجلات — معالجة الرسائل ذات مستوى معين فقط.
التكامل مع أطر العمل — في Symfony و Laravel و Yii2، يُستخدم Monolog تحديدًا.

\n\n

التثبيت

يتم تثبيت Monolog عبر Composer — مدير الحزم القياسي لـ PHP.

composer require monolog/monolog

إذا كنت تستخدم PHP 8.0+، يُنصح بتثبيت أحدث إصدار مستقر. بعد التثبيت، سيظهر مجلد vendor وملف composer.json مع التبعية في المشروع.

\n\n

البداية السريعة

أبسط مثال — تسجيل سجل في ملف:

<?php\nrequire 'vendor/autoload.php';\n\nuse Monolog\\Logger;\nuse Monolog\\Handler\\StreamHandler;\n\n// إنشاء مسجل باسم قناة 'my_app'\n$log = new Logger('my_app');\n// إضافة معالج — الكتابة إلى ملف\n$log->pushHandler(new StreamHandler('app.log', Logger::WARNING));\n\n// الآن يمكننا تسجيل السجلات\n$log->warning('هذا تحذير');\n$log->error('هذا خطأ');\n\necho "تمت كتابة السجلات في app.log";\n?>

بعد تنفيذ السكريبت، سيظهر في ملف app.log شيء مثل:

[2025-04-09T10:30:00.123456+00:00] my_app.WARNING: هذا تحذير [] []\n[2025-04-09T10:30:00.123789+00:00] my_app.ERROR: هذا خطأ [] []

\n\n

الطرق والوظائف الأساسية

دعنا نستعرض الطرق الرئيسية لـ Monolog. جميعها جزء من الفئة Monolog\\Logger أو الفئات المرتبطة بها.

\n\n

1. `pushHandler(HandlerInterface $handler)`

ما يفعله: يضيف معالجًا (handler) إلى المكدس. يمكن أن يحتوي المسجل على عدة معالجات، وسيتلقى كل منها جميع الرسائل (إذا لم يتم تكوين التصفية).

المعلمات:

$handler — كائن ينفذ Monolog\\Handler\\HandlerInterface (مثل StreamHandler، FirePHPHandler، SlackHandler).

مثال:

$log = new Logger('app');\n$log->pushHandler(new StreamHandler('debug.log', Logger::DEBUG));\n$log->pushHandler(new StreamHandler('errors.log', Logger::ERROR));\n// الآن الرسائل ذات المستوى ERROR وما فوق ستُكتب في كلا الملفين

\n\n

2. `addRecord(int $level, string $message, array $context = [])`

ما يفعله: الطريقة الأساسية لتسجيل سجل. عادة لا تُستدعى مباشرة، بل تُستخدم طرق التغليف (debug()، info()، إلخ).

المعلمات:

$level — مستوى التسجيل (ثوابت: Logger::DEBUG، Logger::INFO، Logger::WARNING، إلخ).
$message — نص الرسالة.
$context — مصفوفة من البيانات الإضافية (مثل معرف المستخدم، عنوان IP).

مثال: