كيفية إظهار أخطاء PHP وتفعيل الإبلاغ عنها بشكل صحيح

لماذا يجب تفعيل عرض أخطاء PHP؟

يُعد التعامل مع أخطاء PHP من الأساسيات التي ينبغي على أي مطور فهمها مبكراً. المشكلة أن كثيراً من بيئات الاستضافة أو الخوادم تضبط إعدادات اللغة بشكل يمنع ظهور الأخطاء افتراضياً، وهذا يؤدي إلى استمرار الأعطال أو التنبيهات البرمجية دون أن يلاحظها أحد. لذلك فإن تفعيل الإبلاغ عن الأخطاء في بيئة التطوير المحلية يساعدك على اكتشاف المشكلات مبكراً، وتحسين جودة الشفرة، وتفادي ظهور أخطاء للمستخدم النهائي لاحقاً.

غالباً ما يكتشف المطورون الجدد في PHP أهمية هذه الإعدادات بعد فوات الأوان، عندما يتضح أن التطبيق كان يعمل بينما يخفي في الخلفية سلسلة من الأخطاء والتنبيهات. لهذا من الأفضل ضبط البيئة من البداية بحيث تعرض المشكلات وتُسجلها بوضوح.

كيفية إظهار أخطاء PHP داخل الشفرة

أول خطوة لفهم سلوك الأخطاء في PHP هي استخدام الدالة error_reporting(). تتيح لك هذه الدالة تحديد مستوى الأخطاء التي تريد من PHP الإبلاغ عنها أثناء تنفيذ السكربت، كما يمكن استخدامها أيضاً لمعرفة المستوى الحالي المضبوط في البيئة.

تقبل الدالة error_reporting() معاملاً واحداً من نوع عدد صحيح، ويمثل هذا المعامل مستوى الإبلاغ المطلوب. وإذا استدعيت الدالة من دون أي معاملات، فإنها تعيد المستوى الحالي فقط.

لكل مستوى من مستويات الأخطاء ثابت جاهز داخل PHP. على سبيل المثال، الثابت E_ERROR يساوي القيمة 1، وهذا يعني أنه يمكنك تمرير 1 أو E_ERROR وستحصل على النتيجة نفسها.

عرض مستوى الإبلاغ الحالي

<?php
// echo the current error reporting level
echo error_reporting();

تحديد مستوى معين من الإبلاغ

<?php
// report all Fatal run-time errors.
echo error_reporting(1);

هذا الأسلوب مفيد أثناء اختبار ملف أو جزء محدد من المشروع، لكنه ليس الحل الأفضل لإدارة الأخطاء على مستوى البيئة كاملة. الأفضل عادةً هو ضبط الإعدادات العامة من خلال ملف php.ini.

ضبط إعدادات الإبلاغ عن الأخطاء عبر ملف php.ini

يُعد ملف php.ini المسؤول الرئيسي عن إعدادات PHP في الخادم أو البيئة المحلية. من خلاله يمكنك التحكم في الذاكرة، وحجم الملفات المرفوعة، وسلوك الأخطاء، وطريقة تسجيلها.

إذا لم تكن تعرف مكان هذا الملف، يمكنك إنشاء سكربت بسيط يستخدم الدالة phpinfo() لعرض معلومات تثبيت PHP بالكامل.

<?php
phpinfo();

بعد تشغيل الملف في المتصفح، ابحث عن المسار الخاص بملف php.ini. قد يكون مثلاً في مسار مثل /etc/php/7.3/apache2/php.ini بحسب نظام التشغيل وإعدادات الخادم.

بعد الوصول إلى الملف، افتحه في محرر النصوص وابحث عن القسم المسمى Error handling and logging، وهو القسم الذي يحتوي على أهم الإعدادات المتعلقة بالأخطاء.

أهم مستويات الإبلاغ عن الأخطاء في PHP

داخل ملف php.ini ستجد تعليقات توضيحية تعرض الثوابت المستخدمة لتحديد مستويات الأخطاء، إضافة إلى مجموعة قيم شائعة تساعدك على اختيار الإعداد الأنسب لبيئة التطوير أو الإنتاج.

; Common Values:
; E_ALL (Show all errors, warnings and notices including coding standards.)
; E_ALL & ~E_NOTICE (Show all errors, except for notices)
; E_ALL & ~E_NOTICE & ~E_STRICT (Show all errors, except for notices and coding standards warnings.)
; E_COMPILE_ERROR|E_RECOVERABLE_ERROR|E_ERROR|E_CORE_ERROR (Show only errors)
;
; Default Value: E_ALL & ~E_NOTICE & ~E_STRICT & ~E_DEPRECATED
; Development Value: E_ALL
; Production Value: E_ALL & ~E_DEPRECATED & ~E_STRICT

في بيئة التطوير المحلية، يُنصح غالباً باستخدام E_ALL حتى تتمكن من رؤية جميع الأخطاء والتحذيرات والتنبيهات دون استثناء تقريباً.

error_reporting = E_ALL

يُفضل اعتماد هذا الإعداد منذ بداية أي مشروع جديد، لأنه يمنحك رؤية كاملة لأي مشكلة قد تظهر أثناء التطوير.

إعدادات مهمة مرتبطة بعرض الأخطاء وتسجيلها

إلى جانب التعليمة error_reporting، توجد مجموعة إعدادات أخرى لا تقل أهمية، لأنها تحدد ما إذا كانت الأخطاء ستظهر على الشاشة أو تُحفظ في سجل مخصص.

1. تفعيل عرض الأخطاء مباشرة

التعليمة display_errors تحدد ما إذا كانت PHP ستعرض الأخطاء في الصفحة مباشرة. في بيئة التطوير، من المفيد عادةً ضبطها على On.

display_errors=On

2. أخطاء بدء التشغيل

التعليمة display_startup_errors تتحكم في إظهار الأخطاء التي قد تقع أثناء بدء تشغيل PHP. هذه الأخطاء ترتبط غالباً بإعدادات الخادم أو وحدات PHP، وليس بالشفرة التطبيقية نفسها. لذلك من الأفضل إبقاؤها معطلة ما لم تكن بصدد تتبع مشكلة غامضة.

3. تسجيل الأخطاء في ملف

التعليمة log_errors تحدد ما إذا كانت الأخطاء ستُسجّل في ملف سجل. يُنصح عادةً بتركها مفعّلة، لأن السجل مفيد جداً عند مراجعة المشكلات التي لا تظهر بشكل واضح أثناء التصفح.

4. تحديد مسار ملف السجل

إذا أردت تحديد مكان حفظ الأخطاء يدوياً، يمكنك استخدام التعليمة error_log لتعيين مسار مخصص.

error_log = /path/to/php.log

هذا الإعداد مناسب إذا كنت تريد ملفاً ثابتاً وواضحاً لمراجعة كل أخطاء PHP، لكن إن كنت تعمل على عدة مشاريع في الوقت نفسه، فقد تحتاج إلى تنظيم السجلات بطريقة أدق حتى لا تختلط الأخطاء.

تخصيص سجل أخطاء PHP على خادم Apache

عند استخدام خادم Apache، يمكن ضبط ملف سجل الأخطاء من خلال إعدادات المضيف الافتراضي Virtual Host. مثال على ذلك:

ErrorLog ${APACHE_LOG_DIR}/project-error.log

هذا يعني أن الأخطاء ستُحفظ داخل مجلد سجلات Apache الافتراضي، مثل /var/log/apache2، في ملف باسم project-error.log. ومن الأفضل استبدال كلمة project باسم المشروع الحقيقي لتسهيل تتبع السجلات.

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

متى تستخدم عرض الأخطاء ومتى تعتمد على السجل فقط؟

القاعدة العملية البسيطة هي:

• في بيئة التطوير: فعّل display_errors واستخدم E_ALL.
• في بيئة الإنتاج: تجنب عرض الأخطاء للمستخدم النهائي، وفعّل log_errors مع تسجيلها في ملف آمن.

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

أخطاء شائعة ستظهر بعد تفعيل الإبلاغ الكامل

عند تشغيل الإبلاغ الكامل عن الأخطاء لأول مرة، قد تتفاجأ بظهور عدد كبير من الرسائل في مشروع قديم أو غير منظم جيداً. هذا أمر طبيعي، بل هو دليل على أن النظام بدأ يكشف لك ما كان مخفياً سابقاً.

من الأمثلة الشائعة على ذلك تعريف الثوابت بطريقة غير صحيحة، مثل كتابة اسم الثابت من دون علامات اقتباس داخل الدالة define():

define(CONSTANT, 'Hello world.');

قد تسمح بعض إصدارات PHP بهذا الأسلوب أو كانت تتسامح معه سابقاً، لكنه يؤدي إلى ظهور تنبيه من نوع Notice يشبه الآتي:

Notice: Use of undefined constant CONSTANT - assumed 'CONSTANT'

الحل الصحيح هو تمرير اسم الثابت كسلسلة نصية:

define('CONSTANT', 'Hello world.');

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

أفضل ممارسات التعامل مع أخطاء PHP

1. اضبط error_reporting = E_ALL أثناء التطوير.
2. استخدم display_errors=On محلياً فقط.
3. فعّل log_errors دائماً للاستفادة من السجلات.
4. خصص ملف سجل منفصلاً لكل مشروع إن أمكن.
5. راجع التنبيهات من نوع Notice وWarning بدلاً من تجاهلها، لأنها قد تكون مؤشراً على مشاكل أكبر لاحقاً.
6. لا تعرض تفاصيل الأخطاء على مواقع الإنتاج العامة.

الخلاصة التقنية

تفعيل عرض أخطاء PHP والإبلاغ عنها ليس مجرد خطوة مخصصة للتصحيح، بل هو جزء أساسي من بناء تطبيقات مستقرة وقابلة للصيانة. الإعداد المثالي يبدأ من بيئة تطوير تكشف كل شيء عبر E_ALL، مع تسجيل الأخطاء بوضوح في ملفات مخصصة، ثم الانتقال إلى بيئة إنتاج أكثر تحفظاً تمنع كشف المعلومات الحساسة للمستخدم. تقنياً، كل تنبيه تراه مبكراً هو تكلفة أقل في المستقبل، وكل سجل أخطاء منظم يعني وقتاً أقل في تتبع الأعطال وإصلاحها.