إظهار الأخطاء في PHP: display_errors وE_ALL

لإظهار أخطاء PHP، ضع هذين السطرين في أعلى السكربت: ini_set('display_errors', '1'); وerror_reporting(E_ALL);. الأول يجعل PHP تطبع رسائل الأخطاء، والثاني يجعلها تبلّغ عن كل أنواع الأخطاء، بما فيها التحذيرات وإشعارات الإهمال (deprecations).

<?php
ini_set('display_errors', '1');
ini_set('display_startup_errors', '1');
error_reporting(E_ALL);

بعد ذلك، يطبع خطأ مثل قراءة متغير لم يُعيَّن قط رسالة فيها الملف ورقم السطر بدلًا من أن يفشل بصمت:

Warning: Undefined variable $total in /home/index.php on line 7

عند استدعاء error_reporting() دون وسيط، تعيد الإعداد الحالي كعدد. اضغط Run لتعيين مستوى ثم فكّه إلى أسمائه:

<?php
error_reporting(E_ALL & ~E_DEPRECATED);
$level = error_reporting();

echo "Current level: $level (E_ALL is " . E_ALL . ")\n";

foreach (get_defined_constants(true)['Core'] as $name => $value) {
    if (str_starts_with($name, 'E_') && $name !== 'E_ALL') {
        echo str_pad($name, 20), ($level & $value) ? "reported" : "off", "\n";
    }
}

كل نوع خطأ هو بت واحد، لذا تعني E_ALL & ~E_DEPRECATED «كل شيء ما عدا إشعارات الإهمال». غيّر السطر الأول إلى error_reporting(E_ERROR | E_WARNING); وشغّله مرة أخرى.

إظهار الأخطاء في php.ini

الإعداد داخل السكربت لا يسري إلا بعد بدء تنفيذ السكربت. لإظهار الأخطاء في كل السكربتات، بما فيها أخطاء التحليل، عدّل php.ini (اعثر عليه بالأمر php --ini):

; Development
display_errors = On
display_startup_errors = On
error_reporting = E_ALL

أعد تشغيل Apache أو PHP-FPM بعد التعديل. أما الخادم المدمج php -S وسطر الأوامر فيقرآن الملف عند كل تشغيل. وعلى الاستضافة المشتركة دون وصول إلى php.ini، يقبل Apache مع mod_php أيضًا أسطرًا في .htaccess:

php_flag display_errors on
php_value error_reporting -1

القيمة -1 تعيّن كل البتات، وهي تساوي E_ALL.

مستويات الأخطاء

حوّل PHP 8.0 كثيرًا من التحذيرات القديمة إلى استثناءات: القسمة على صفر بـ / وتمرير نوع خاطئ إلى دالة مدمجة يطلقان الآن صنفًا فرعيًا من Error، كما يحدث عند استدعاء دالة غير معرّفة منذ PHP 7. يمكنك التقاط الثلاثة:

<?php
$attempts = [
    fn() => 10 / 0,
    fn() => strlen([]),
    fn() => undefinedFunction(),
];

foreach ($attempts as $attempt) {
    try {
        $attempt();
    } catch (Throwable $e) {
        echo get_class($e), ": ", $e->getMessage(), "\n";
    }
}

الاستثناءات مشروحة في try وcatch. أما التحذيرات والإشعارات وإشعارات الإهمال فما زالت تمر عبر نظام الإبلاغ عن الأخطاء الموصوف هنا.

تسجيل الأخطاء بدلًا من عرضها

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

; Production
display_errors = Off
log_errors = On
error_log = /var/log/php/app-errors.log
error_reporting = E_ALL

أبقِ error_reporting = E_ALL في الإنتاج. خفضه لا يجعل الأخطاء تختفي، بل يمنعك فقط من معرفتها. ويمكن أن تذهب رسائلك الخاصة إلى السجل نفسه عبر error_log():

<?php
error_log("Payment failed for order 1042");

ثم راقب الملف أثناء الاختبار: tail -f /var/log/php/app-errors.log.

تحويل التحذيرات إلى استثناءات باستخدام set_error_handler

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

<?php
set_error_handler(function (int $severity, string $message, string $file, int $line): bool {
    throw new ErrorException($message, 0, $severity, $file, $line);
});

$prices = ['bread' => 4.5, 'milk' => 1.2];

try {
    echo "Bread costs {$prices['bread']}\n";
    echo "Cheese costs {$prices['cheese']}\n";
} catch (ErrorException $e) {
    echo "Caught: ", $e->getMessage(), " on line ", $e->getLine(), "\n";
}

restore_error_handler();

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

<?php
set_error_handler(function (int $severity, string $message): bool {
    if ($severity === E_DEPRECATED || $severity === E_USER_DEPRECATED) {
        echo "[log] deprecated: $message\n";
        return true; // handled, PHP does nothing more
    }
    throw new ErrorException($message, 0, $severity);
});

trigger_error("oldFunction() is deprecated, use newFunction()", E_USER_DEPRECATED);

try {
    trigger_error("Config value 'timeout' is missing", E_USER_WARNING);
} catch (ErrorException $e) {
    echo "Exception: ", $e->getMessage(), "\n";
}

الأخطاء القاتلة وأخطاء التحليل لا تصل إلى المعالج أبدًا، لأن السكربت لا يستطيع المتابعة بعدها. ولتسجيلها، سجّل دالة إيقاف (shutdown function) تقرأ error_get_last().

قراءة آخر خطأ باستخدام error_get_last

بعض الدوال تعيد false ولا تبلّغ عن السبب إلا كتحذير، مثل file_get_contents على ملف مفقود. تعيد error_get_last() هذا التحذير كمصفوفة، وهذا مفيد عندما تريد عرض رسالتك الخاصة:

<?php
$content = @file_get_contents('missing-config.json');

if ($content === false) {
    $error = error_get_last();
    echo "Could not read the file.\n";
    echo "Type: ", $error['type'] === E_WARNING ? 'E_WARNING' : $error['type'], "\n";
    echo "Message: ", $error['message'], "\n";
}

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

خطأ شائع: الأخطاء مفعّلة لكن الصفحة ما زالت فارغة

إذا أضفت ini_set('display_errors', '1') وما زلت ترى صفحة بيضاء، فالخطأ على الأرجح خطأ تحليل. تحلّل PHP الملف كله قبل تنفيذ السطر الأول، لذا فإن ; أو } مفقودة توقف كل شيء قبل تنفيذ ini_set. افحص الملف من الطرفية، فهي تطبع الرسالة دائمًا:

php -l index.php

Errors parsing index.php
PHP Parse error:  syntax error, unexpected token "," in index.php on line 2

يشير رقم السطر إلى حيث توقفت PHP، وهو غالبًا السطر الذي يلي الخطأ الحقيقي. أصلحه، وشغّل php -l مرة أخرى حتى يقول No syntax errors detected، ثم أعد تحميل الصفحة.