Psr/Log PHP: الدليل الشامل مع أمثلة عملية

تسجيل الأخطاء (Logging) هو أحد الركائز الأساسية في تطوير أي تطبيق جاد. بدونه، يستحيل تتبع الأخطاء في بيئة الإنتاج، أو مراقبة سلوك المستخدمين، أو تحليل أداء النظام. لكن عندما يستخدم المشروع عدة مكتبات، كل منها يسجل الأخطاء بطريقته الخاصة، يواجه المطور فوضى عارمة: مستويات مختلفة، صيغ مختلفة، وطرق إخراج متباينة. لحل هذه المشكلة تحديدًا، تم إنشاء معيار PSR-3 (Logger Interface).

Psr/Log ليس مكتبة تسجيل أخطاء بحد ذاتها، بل هو واجهة معيارية (مجموعة عقود) تحدد الشكل الذي يجب أن يكون عليه المسجل العام (Logger) في PHP. يوفر ثماني دوال لتسجيل الرسائل بمستويات أهمية مختلفة (emergency, alert, critical, error, warning, notice, info, debug)، بالإضافة إلى الدالة الشاملة log(). أي مكتبة تطبق معيار PSR-3 يمكن دمجها بسهولة في أي مشروع يتوقع هذه الواجهة. وهذا يتيح للمطور تغيير مكتبة التسجيل (مثلًا من Monolog إلى Analog) دون تعديل كود التطبيق.

في هذه المقالة، سنشرح مكتبة psr/log بالتفصيل، بدءًا من التثبيت وصولًا إلى أمثلة عملية متقدمة. ستتعلم كيفية استخدام كل دالة بشكل صحيح، وكيفية تنسيق الرسائل باستخدام العناصر النائبة (placeholders)، وكيفية تجنب الأخطاء الشائعة. المحتوى مفيد لكل من المبتدئين في PHP والمطورين المحترفين الراغبين في تنظيم معرفتهم.

التثبيت

يتم تثبيت مكتبة psr/log عبر Composer، مدير الحزم القياسي في PHP. قم بتنفيذ الأمر التالي في الطرفية:

composer require psr/log

بعد التثبيت، سيظهر مجلد vendor/psr/log في مشروعك. إذا كنت تستخدم إطار عمل (Laravel, Symfony)، فمن المحتمل أن يكون PSR-3 مضمنًا بالفعل. لتشغيل أداة التحميل التلقائي (autoloader) في ملف PHP الخاص بك، أضف السطر التالي:

require __DIR__ . '/vendor/autoload.php';

ملاحظة مهمة: psr/log هو مجرد واجهة. لتسجيل الأخطاء فعليًا، ستحتاج إلى تطبيق عملي مثل monolog/monolog. لتثبيت Monolog:

composer require monolog/monolog

بداية سريعة

لننشئ مثالًا بسيطًا لتسجيل الأخطاء باستخدام Monolog (أشهر تطبيق لـ PSR-3).

<?php
require 'vendor/autoload.php';

use Monolog\Logger;
use Monolog\Handler\StreamHandler;

// إنشاء مسجل باسم 'my_logger'
$log = new Logger('my_logger');

// إضافة معالج: كتابة جميع الرسائل من مستوى DEBUG فما فوق إلى ملف app.log
$log->pushHandler(new StreamHandler(__DIR__ . '/app.log', Logger::DEBUG));

// تسجيل عدة رسائل
$log->info('تم تشغيل التطبيق');
$log->warning('تعذر تحميل ملف الإعدادات، تم استخدام القيم الافتراضية');
$log->error('خطأ حرج: قاعدة البيانات غير متاحة');

echo "تم تسجيل الأخطاء. تحقق من ملف app.log";

بعد تنفيذ هذا السكريبت، سترى في ملف app.log ما يلي تقريبًا:

[2025-04-10T15:30:45.123456+00:00] my_logger.INFO: تم تشغيل التطبيق [] []
[2025-04-10T15:30:45.123789+00:00] my_logger.WARNING: تعذر تحميل ملف الإعدادات، تم استخدام القيم الافتراضية [] []
[2025-04-10T15:30:45.124012+00:00] my_logger.ERROR: خطأ حرج: قاعدة البيانات غير متاحة [] []

هذا مثال عملي بسيط. الآن سنشرح كل دالة من دوال الواجهة بالتفصيل.

الدوال الأساسية لواجهة Psr\Log\LoggerInterface

تحدد واجهة Psr\Log\LoggerInterface 9 دوال. الثمانية الأولى مخصصة لمستويات تسجيل محددة، والتاسعة هي الدالة الشاملة log()

أيضاً في المكتبة

دمج مقاييس Prometheus في تطبيقات Kotlin: دليل شامل إرسال الرسائل القصيرة (SMS) باستخدام Kotlin: مكتبة API للتكامل Armadillo C++: دليل شامل مع أمثلة عملية دليل Flysystem PHP الشامل: أمثلة وطرق الاستخدام تحليل HTML في Java: أفضل المكتبات وأمثلة الكود