اكتب للبدء بالبحث
    Esc للإغلاق · مدعوم ببحث فوري في كامل الموقع

    كيف ترى أخطاء PHP؟ دليل عملي لتفعيل عرض الأخطاء وتسجيلها

    · فريق AraBay
    شروحات تقنية

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

    ini_set('display_errors', 1);
error_reporting(E_ALL);

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

    لماذا لا تظهر الأخطاء أصلًا؟

    في معظم إعدادات الاستضافة الحديثة (PHP 8.3 و8.4 وما بعدها) يكون خيار display_errors مُعطّلًا افتراضيًا لأسباب أمنية. النتيجة أنك ترى صفحة بيضاء بدل رسالة الخطأ. المشكلة ليست أن الخطأ اختفى، بل أن PHP كتبه في مكان لا تراه وهو سجل الأخطاء (error log). لذلك أول خطوة دائمًا هي أن تقرر: هل تريد إظهار الخطأ على الشاشة، أم قراءته من السجل؟

    فخ شائع: عرض الأخطاء البرمجي لا يكشف أخطاء الصياغة

    هذه نقطة يغفل عنها كثير من الشروحات. عندما تضع ini_set('display_errors', 1) داخل الملف، فإن السطر لا يُنفَّذ إلا بعد أن يقرأ PHP الملف كاملًا بنجاح. فإذا كان الخطأ نفسه خطأ صياغة (Syntax Error) مثل قوس ناقص أو فاصلة منقوطة مفقودة في نفس الملف، فسيفشل الملف كله قبل الوصول إلى سطر التفعيل، وستبقى الشاشة بيضاء رغم الكود.

    الحل في هذه الحالة أحد أمرين:

    1. فعّل عرض الأخطاء من php.ini (يعمل قبل تنفيذ أي ملف).
    2. أو افتح سجل الأخطاء الذي يسجّل حتى أخطاء الصياغة.

    تفعيل عرض الأخطاء بشكل دائم عبر php.ini

    للتحكم على مستوى الخادم كله، عدّل ملف php.ini. أولًا اعرف مكانه بتنفيذ:

    <?php phpinfo();

    وابحث في المخرجات عن سطر «Loaded Configuration File». ثم افتح الملف واضبط القيم التالية:

    display_errors = On
display_startup_errors = On
error_reporting = E_ALL

    بعد الحفظ، أعد تشغيل خادم الويب (Apache أو PHP-FPM/Nginx) حتى تسري التغييرات. إذا كنت على استضافة مشتركة ولا تملك صلاحية تعديل php.ini، فغالبًا يمكنك وضع نفس الإعدادات في ملف .user.ini داخل مجلد موقعك، أو استخدام ملف .htaccess مع Apache عبر أسطر مثل php_flag display_errors On.

    الأفضل للمواقع الحقيقية: سجل الأخطاء لا عرضها

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

    ini_set('display_errors', 0);
ini_set('log_errors', 1);
error_reporting(E_ALL);

    بعدها اقرأ الأخطاء من ملف السجل. لمعرفة مساره نفّذ echo ini_get('error_log');، وإن كان فارغًا فستجد الأخطاء عادةً في سجل خادم الويب مثل /var/log/apache2/error.log أو /var/log/nginx/error.log. يمكنك أيضًا تحديد ملف خاص بك عبر error_log = /path/to/php-error.log في php.ini.

    عرض على الشاشة أم تسجيل في ملف؟

    المعيارالعرض على الشاشةالتسجيل في ملف
    البيئة المناسبةالتطوير المحليالموقع المنشور
    الأمانخطر: يكشف تفاصيل الخادمآمن: لا يراه الزائر
    سرعة الاكتشاففوري أمام عينكيحتاج فتح السجل
    يلتقط أخطاء الصياغةلا (إن فُعّل داخل الكود)نعم
    مناسب للأخطاء المتقطعةلانعم، يبقى سجل دائم

    القاعدة العملية: اعرض أثناء التطوير، وسجّل في الإنتاج.

    أدوات تسهّل عليك التصحيح

    • Xdebug: الأداة الأقوى؛ تتيح نقاط توقف (breakpoints) لتتبع الكود سطرًا سطرًا داخل المحرر، وتعرض تتبع الاستدعاء (stack trace) بشكل مقروء.
    • أطر العمل الحديثة: إن كنت تستخدم Laravel، لا تعبث بـ php.ini؛ فقط اضبط APP_DEBUG=true في ملف .env لبيئة التطوير وfalse للإنتاج. أما Symfony فيبدّل السلوك حسب متغير البيئة APP_ENV. هذه الأطر تعرض صفحة خطأ مفصّلة وجميلة بديلة عن الشاشة البيضاء.
    • صفحة الأخطاء المنسّقة: مكتبة مثل Whoops تحوّل الأخطاء إلى صفحة واضحة تعرض السطر ومحيطه.

    نصيحة من واقع التجربة

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

    الأسئلة الشائعة

    لماذا أرى صفحة بيضاء بلا أي رسالة؟ لأن display_errors معطّل، وغالبًا الخطأ خطأ صياغة أو خطأ فادح. افتح سجل الأخطاء أو فعّل العرض من php.ini، فالتفعيل داخل الملف لا يكفي مع أخطاء الصياغة.

    هل أضع ini_set('display_errors', 1) في موقعي الحقيقي؟ لا. اتركه مطفأً في الإنتاج وفعّل log_errors بدلًا منه، لأن عرض الأخطاء يكشف معلومات حسّاسة عن الخادم.

    أين أجد ملف سجل الأخطاء؟ نفّذ echo ini_get('error_log'); لمعرفة المسار، أو راجع سجل خادم الويب مثل error.log الخاص بـ Apache أو Nginx.

    علامة @ لإخفاء الأخطاء، هل أستخدمها؟ تجنّبها؛ فهي تُسكت الأخطاء بدل حلّها وتصعّب التصحيح لاحقًا. عالج سبب الخطأ بدل إخفائه.

    #PHP#تصحيح الأخطاء#display_errors#php.ini#سجل الأخطاء#Xdebug