Mostrare gli errori in PHP: display_errors ed E_ALL

Per mostrare gli errori PHP, metti queste righe in cima allo script: ini_set('display_errors', '1'); e error_reporting(E_ALL);. La prima fa stampare a PHP i messaggi di errore, la seconda gli fa segnalare ogni tipo di errore, compresi warning e deprecazioni.

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

Con queste righe, un errore come leggere una variabile mai impostata stampa un messaggio con file e numero di riga invece di fallire in silenzio:

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

error_reporting() chiamata senza argomenti restituisce l'impostazione corrente come numero. Premi Run per impostare un livello e ritradurlo in nomi:

<?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";
    }
}

Ogni tipo di errore è un bit, quindi E_ALL & ~E_DEPRECATED significa "tutto tranne le deprecazioni". Cambia la prima riga in error_reporting(E_ERROR | E_WARNING); ed eseguilo di nuovo.

Mostrare gli errori in php.ini

Un'impostazione nello script vale solo dopo che lo script ha iniziato a girare. Per mostrare gli errori in ogni script, errori di sintassi compresi, modifica php.ini (lo trovi con php --ini):

; Development
display_errors = On
display_startup_errors = On
error_reporting = E_ALL

Riavvia Apache o PHP-FPM dopo la modifica. Il server integrato php -S e la riga di comando leggono il file a ogni avvio. Su un hosting condiviso senza accesso a php.ini, Apache con mod_php accetta anche righe in .htaccess:

php_flag display_errors on
php_value error_reporting -1

-1 imposta tutti i bit, che equivale a E_ALL.

I livelli di errore

PHP 8.0 ha trasformato molti vecchi warning in eccezioni: dividere per zero con / e passare il tipo sbagliato a una funzione integrata ora lanciano una sottoclasse di Error, come succede da PHP 7 quando chiami una funzione non definita. Puoi catturarli tutti e tre:

<?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";
    }
}

Le eccezioni sono trattate in try e catch. Warning, notice e deprecazioni passano ancora dal sistema di segnalazione degli errori descritto qui.

Registrare gli errori nel log invece di mostrarli

Su un sito in produzione i visitatori non devono mai vedere messaggi di errore: rivelano percorsi, SQL e codice. Scrivili invece in un file di log:

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

Mantieni error_reporting = E_ALL in produzione. Abbassarlo non fa sparire gli errori, impedisce solo che tu ne venga a sapere. Anche i tuoi messaggi possono finire nello stesso log con error_log():

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

Poi tieni d'occhio il file mentre fai i test: tail -f /var/log/php/app-errors.log.

Trasformare i warning in eccezioni con set_error_handler

set_error_handler sostituisce la gestione predefinita di warning, notice e deprecazioni con una tua funzione. Uno schema comune li converte tutti in ErrorException, così una chiave di array dimenticata ferma il codice come qualsiasi altra eccezione e può essere catturata:

<?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();

Il gestore riceve il livello dell'errore come primo argomento, quindi può trattare i livelli in modo diverso. Questo registra solo le deprecazioni e trasforma tutto il resto in un'eccezione:

<?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";
}

Gli errori fatali e gli errori di sintassi non arrivano mai al gestore, perché dopo di essi lo script non può continuare. Per registrarli, registra una funzione di shutdown che legge error_get_last().

Leggere l'ultimo errore con error_get_last

Alcune funzioni restituiscono false e riportano il motivo solo come warning, per esempio file_get_contents su un file mancante. error_get_last() restituisce quel warning come array, utile quando vuoi mostrare un tuo messaggio:

<?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";
}

L'operatore @ davanti alla chiamata sopprime il messaggio per quella sola espressione. Usalo con parsimonia e solo quando controlli il risultato subito dopo, come qui; una @ da sola nasconde soltanto i bug.

Errore comune: gli errori sono attivi, ma la pagina è ancora bianca

Se hai aggiunto ini_set('display_errors', '1') e vedi ancora una pagina bianca, probabilmente l'errore è di sintassi. PHP analizza tutto il file prima di eseguire la prima riga, quindi un ; o una } mancanti fermano tutto prima che ini_set venga eseguita. Controlla il file dal terminale, che stampa sempre il messaggio:

php -l index.php

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

Il numero di riga indica dove PHP si è arreso, che spesso è la riga dopo l'errore vero. Correggilo, esegui di nuovo php -l finché non dice No syntax errors detected, poi ricarica la pagina.