In un'applicazione PHP gli errori fanno parte del normale ciclo di sviluppo. Un parametro mancante,una query SQL non valida,un file non disponibile o un'eccezione generata da un servizio esterno possono interrompere l'esecuzione del codice e produrre comportamenti inattesi.

In ambiente di sviluppo è importante ottenere quante più informazioni possibili sull'errore. In produzione,al contrario,mostrare direttamente all'utente il percorso di un file,una query SQL o uno stack trace può rappresentare un problema di sicurezza.

La gestione degli errori PHP deve quindi perseguire due obiettivi differenti: fornire agli sviluppatori informazioni tecniche sufficienti per individuare la causa del problema e impedire che tali informazioni vengano esposte all'esterno.

Per ottenere questo risultato è necessario combinare logging,exception handling,controllo degli errori e strumenti di debugging.

Errori PHP ed eccezioni non sono la stessa cosa

Uno degli aspetti fondamentali nella programmazione PHP moderna consiste nel distinguere tra errori,exception ed errori fatali.

Le versioni moderne di PHP utilizzano una gerarchia basata sull'interfaccia Throwable,all'interno della quale rientrano principalmente Error ed Exception.

Un errore può essere rappresentato,ad esempio,da un problema di tipo:

TypeError

mentre un'applicazione può generare intenzionalmente un'eccezione attraverso:

throw new Exception("Operazione non valida");

Questi meccanismi possono essere intercettati con try e catch,ma devono essere utilizzati correttamente in funzione del tipo di problema.

La struttura try catch

Il costrutto try/catch permette di gestire un'eccezione senza necessariamente interrompere l'intero flusso applicativo.

Un esempio semplice è:

try {
    $risultato = eseguiOperazione();
} catch (Exception $e) {
    // gestione dell'eccezione
}

In PHP moderno è spesso preferibile intercettare Throwable quando si vuole gestire sia Exception sia Error:

try {
    $risultato = eseguiOperazione();
} catch (Throwable $e) {
    // gestione dell'errore
}

La differenza è importante perché non tutti gli errori vengono rappresentati dalla classe Exception.

Non utilizzare try catch ovunque

Un errore frequente consiste nell'inserire try/catch indiscriminatamente in ogni funzione.

Il catch non dovrebbe semplicemente nascondere il problema.

Un codice come:

try {
    eseguiOperazione();
} catch (Throwable $e) {
}

è particolarmente problematico perché intercetta l'errore senza registrarlo e senza informare il livello superiore dell'applicazione.

Il risultato può essere un sistema apparentemente funzionante ma con errori invisibili.

Una corretta gestione deve invece decidere cosa fare dell'eccezione: registrarla,trasformarla,propagarla oppure restituire una risposta appropriata al chiamante.

Logging: registrare gli errori PHP

Il logging è uno degli strumenti fondamentali per la diagnostica.

PHP permette di utilizzare la funzione:

error_log("Errore durante l'elaborazione della richiesta");

per inviare un messaggio al sistema di logging configurato.

In un'applicazione reale è preferibile utilizzare un sistema strutturato che permetta di distinguere livelli e categorie di errore.

Un log efficace dovrebbe contenere informazioni utili come timestamp,livello dell'errore,componente coinvolto,identificativo della richiesta e messaggio tecnico.

Bisogna però evitare di inserire nei log password,token,chiavi API,dati personali non necessari o altri segreti.

Configurare error_reporting

Durante lo sviluppo è utile configurare PHP affinché segnali il maggior numero possibile di problemi.

Una configurazione comune è:

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

E_ALL abilita la segnalazione delle categorie di errori previste dalla versione di PHP utilizzata.

display_errors determina invece se gli errori devono essere visualizzati direttamente nell'output.

Questa distinzione è fondamentale perché una configurazione adatta all'ambiente di sviluppo non dovrebbe essere utilizzata indiscriminatamente in produzione.

display_errors in produzione

Su un server pubblico è generalmente preferibile evitare:

ini_set('display_errors', '1');

perché un errore potrebbe mostrare informazioni interne all'applicazione.

Un semplice warning potrebbe rivelare il percorso filesystem:

/var/www/html/app/includes/database.php

oppure uno stack trace potrebbe mostrare classi,funzioni,query o componenti dell'architettura.

In produzione è quindi più appropriato registrare l'errore nei log e mostrare all'utente un messaggio generico.

Il principio è semplice: dettagli tecnici nei log,informazioni minimali all'utente.

log_errors e gestione dei log

La direttiva:

log_errors = On

permette a PHP di registrare gli errori attraverso il sistema di logging configurato.

È possibile utilizzare anche:

error_log = /percorso/php-error.log

per definire un file di destinazione.

La configurazione esatta dipende dall'ambiente. PHP può infatti essere eseguito attraverso Apache,Nginx e PHP-FPM oppure attraverso altre architetture.

In un'infrastruttura aziendale è importante evitare che i file di log crescano indefinitamente. La log rotation deve essere configurata per evitare di saturare lo spazio disponibile sul server.

Errori PHP e server web

La diagnostica non deve fermarsi al log di PHP.

In un ambiente Linux con Nginx e PHP-FPM,ad esempio,è possibile che un problema venga registrato sia dal processo PHP-FPM sia dal web server.

Un errore 502 Bad Gateway potrebbe infatti derivare da un problema nella comunicazione tra Nginx e PHP-FPM,non necessariamente da un semplice errore nel codice PHP.

In un ambiente Apache,alcune informazioni possono invece essere disponibili nei log di Apache.

Per questo motivo il debugging di un'applicazione web richiede spesso l'analisi coordinata di più livelli.

PHP-FPM e gestione degli errori

Quando PHP viene eseguito attraverso PHP-FPM,il processo applicativo è separato dal web server.

Questa architettura permette di gestire in maniera più efficiente i processi PHP,ma introduce ulteriori componenti da monitorare.

In caso di problemi è necessario verificare lo stato di PHP-FPM,il relativo log e la comunicazione con Nginx o Apache.

Un'applicazione che improvvisamente restituisce 502 può avere problemi legati al processo PHP-FPM,al timeout,al numero massimo di worker oppure a un errore applicativo particolarmente pesante.

Eccezioni personalizzate

In applicazioni di una certa complessità può essere utile definire eccezioni specifiche.

Per esempio:

class DatabaseException extends Exception
{
}

Questo permette di distinguere una problematica relativa al database da altre categorie di errore.

Un'architettura più strutturata può utilizzare gerarchie di eccezioni per rappresentare differenti livelli applicativi.

In questo modo il codice chiamante può decidere come gestire ciascuna categoria.

Throwable e gerarchia delle eccezioni

PHP moderno permette di utilizzare:

catch (Throwable $e)

quando si desidera intercettare sia Exception sia Error.

L'oggetto $e fornisce informazioni importanti attraverso metodi come:

$e->getMessage();
$e->getFile();
$e->getLine();
$e->getTrace();
$e->getTraceAsString();

Queste informazioni sono estremamente utili durante il debugging.

Lo stack trace permette infatti di ricostruire la sequenza di chiamate che ha portato all'errore.

Stack trace: capire da dove arriva un errore

Lo stack trace rappresenta una sorta di percorso inverso dell'esecuzione.

Supponiamo che un controller richiami un service,che a sua volta richiami una funzione per eseguire una query SQL. Se quest'ultima genera un'eccezione,lo stack trace può mostrare la catena di chiamate.

Questo permette di individuare non soltanto la riga nella quale l'errore è stato rilevato,ma anche il percorso che ha portato a quella situazione.

Durante il debugging questa informazione può essere più importante del semplice messaggio dell'errore.

Logging delle eccezioni

Quando un'eccezione viene intercettata,è possibile registrarla:

try {
    eseguiOperazione();
} catch (Throwable $e) {
    error_log(
        $e->getMessage() . ' in ' .
        $e->getFile() . ':' .
        $e->getLine()
    );

    throw $e;
}

La scelta di rilanciare l'eccezione con throw $e dipende dall'architettura dell'applicazione.

Se il livello corrente non è responsabile della gestione definitiva dell'errore,è spesso preferibile registrare l'informazione e lasciare che l'eccezione venga gestita da un livello superiore.

Exception handler globale

PHP permette di definire un gestore globale attraverso:

set_exception_handler(function (Throwable $e) {
    error_log($e->getMessage());
});

Questo meccanismo permette di intercettare le eccezioni non gestite.

In un'applicazione web può essere utilizzato per evitare che un'eccezione non gestita produca una pagina contenente informazioni tecniche.

Il gestore globale può registrare l'errore e restituire una risposta controllata.

Error handler personalizzato

PHP permette inoltre di utilizzare:

set_error_handler()

per intercettare determinate categorie di errori.

Un handler personalizzato può essere utilizzato per trasformare alcune segnalazioni PHP in eccezioni:

set_error_handler(function ($severity, $message, $file, $line) {
    throw new ErrorException(
        $message,
        0,
        $severity,
        $file,
        $line
    );
});

Questa tecnica deve essere utilizzata con attenzione perché non tutti gli errori possono essere gestiti nello stesso modo.

L'obiettivo dovrebbe essere costruire un comportamento coerente e prevedibile,non semplicemente intercettare qualsiasi segnalazione.

Errori fatali e shutdown handler

Alcuni errori possono terminare l'esecuzione dello script prima che il normale flusso applicativo possa gestirli.

In determinati casi è possibile utilizzare:

register_shutdown_function()

insieme a:

error_get_last()

per verificare l'ultimo errore registrato prima della terminazione.

Questa tecnica può essere utile per diagnosticare alcuni errori critici,ma non deve essere considerata un sostituto di una corretta gestione delle eccezioni.

PDO e gestione degli errori SQL

Nelle applicazioni PHP che utilizzano MySQL o MariaDB,la gestione delle eccezioni del database è particolarmente importante.

Con PDO è possibile configurare:

$pdo->setAttribute(
    PDO::ATTR_ERRMODE,
    PDO::ERRMODE_EXCEPTION
);

In questo modo gli errori SQL vengono trasformati in eccezioni PDO.

Un esempio:

try {
    $stmt = $pdo->prepare(
        "SELECT * FROM clienti WHERE id = :id"
    );

    $stmt->execute([
        ':id' => $id
    ]);
} catch (PDOException $e) {
    error_log($e->getMessage());
}

Questo approccio permette di centralizzare la gestione degli errori del database e impedisce che problemi SQL vengano ignorati.

Non registrare password e dati sensibili

Durante il debugging è facile commettere un errore importante: registrare nei log troppi dati.

Un esempio pericoloso sarebbe:

error_log(print_r($_POST, true));

Se il form contiene password,token o altri dati sensibili,queste informazioni potrebbero finire permanentemente nei log.

I log devono quindi essere progettati considerando anche la sicurezza.

È preferibile registrare l'identificativo della richiesta,l'utente tecnico coinvolto,l'endpoint e il tipo di errore senza salvare indiscriminatamente tutto il contenuto della richiesta.

Debugging in ambiente di sviluppo

Durante lo sviluppo è possibile utilizzare strumenti molto più invasivi.

L'obiettivo è ottenere informazioni dettagliate sull'esecuzione del codice,individuando variabili,stack trace,query e condizioni che hanno prodotto l'errore.

Il debugging non consiste semplicemente nell'inserire var_dump() ovunque.

In un progetto strutturato è preferibile utilizzare un debugger,in modo da poter interrompere l'esecuzione in punti specifici e analizzare lo stato delle variabili.

Xdebug: debugging professionale di PHP

Uno degli strumenti più importanti per il debugging PHP è Xdebug.

Xdebug permette di utilizzare breakpoint,stack trace dettagliati,analisi delle variabili e profiling.

Con un IDE compatibile è possibile avviare una sessione di debugging e fermare l'esecuzione su una determinata riga.

Questo permette di osservare direttamente il valore delle variabili e il percorso seguito dal codice.

Per applicazioni complesse è molto più efficace rispetto alla semplice stampa di informazioni attraverso echo o var_dump().

Breakpoint e debugging step by step

Un breakpoint permette di sospendere temporaneamente l'esecuzione del programma in un punto specifico.

Durante la pausa è possibile osservare variabili locali,proprietà degli oggetti,parametri delle funzioni e stack delle chiamate.

Si può quindi procedere passo dopo passo attraverso il codice per capire dove viene introdotto il comportamento errato.

Questo approccio è particolarmente utile per problemi difficili da riprodurre o per applicazioni con numerose chiamate tra controller,service,repository e database.

Debugging e query SQL

Quando un'applicazione PHP utilizza un database,il debugging deve includere anche la parte SQL.

Un errore può essere causato da una query costruita in modo errato,da un parametro con tipo inatteso,da un vincolo FOREIGN KEY,da una colonna inesistente o da un problema di transazione.

In questi casi il messaggio dell'eccezione PDO rappresenta un'importante fonte di informazioni.

È però necessario evitare di mostrare direttamente il messaggio SQL all'utente finale.

Logging strutturato

In applicazioni di dimensioni medio-grandi è preferibile utilizzare un sistema di logging strutturato invece di affidarsi esclusivamente a error_log().

Una libreria molto utilizzata nell'ecosistema PHP è Monolog,che permette di gestire livelli di log,handler e differenti destinazioni.

Un'applicazione può quindi distinguere tra:

DEBUG
INFO
NOTICE
WARNING
ERROR
CRITICAL

La possibilità di filtrare questi livelli permette di evitare che i log diventino semplicemente un'enorme quantità di testo difficile da analizzare.

Log e identificazione delle richieste

In un'applicazione web è particolarmente utile associare gli errori a un request ID.

Quando un utente segnala un problema,il sistema può generare un identificativo univoco della richiesta.

Il log può quindi contenere:

request_id
timestamp
endpoint
user_id
exception
file
line

senza dover necessariamente registrare l'intero contenuto della richiesta.

Questo permette di correlare più eventi e facilita notevolmente l'attività di troubleshooting.

Errori HTTP e API PHP

Le applicazioni PHP che espongono API devono gestire gli errori in modo differente rispetto a una normale pagina HTML.

Un endpoint REST dovrebbe restituire un appropriato HTTP status code e una risposta strutturata.

Per esempio:

{
    "error": "Internal server error",
    "request_id": "abc123"
}

Il dettaglio tecnico dell'eccezione rimane nei log,mentre il client riceve soltanto le informazioni necessarie.

In produzione è preferibile non restituire stack trace,percorso dei file o query SQL all'interno della risposta API.

Ambiente development,staging e production

La configurazione della gestione degli errori dovrebbe cambiare in funzione dell'ambiente.

In development è possibile utilizzare logging dettagliato,debugger e visualizzazione degli errori.

In staging è opportuno avvicinarsi alla configurazione di produzione mantenendo comunque strumenti diagnostici sufficienti per i test.

In production bisogna privilegiare sicurezza,stabilità e logging centralizzato,evitando di mostrare dettagli interni all'utente.

La separazione degli ambienti è quindi una componente importante anche della gestione degli errori.

Come evitare che un errore diventi un problema di sicurezza

Un errore PHP può diventare una vulnerabilità se rivela informazioni sufficienti per comprendere l'architettura interna dell'applicazione.

Percorsi filesystem,versioni dei componenti,query SQL,nomi delle tabelle,stack trace e configurazioni possono fornire informazioni utili a un attaccante.

La gestione degli errori deve quindi seguire il principio del least information disclosure.

L'utente deve ricevere soltanto ciò che gli serve per comprendere che l'operazione non è andata a buon fine. Gli sviluppatori devono invece poter recuperare tutti i dettagli necessari attraverso i sistemi di logging e monitoraggio.

La gestione degli errori come parte dell'architettura

In un'applicazione PHP professionale la gestione degli errori non dovrebbe essere aggiunta quando il progetto è già terminato.

Logging,exception handling,monitoraggio e debugging dovrebbero essere considerati parte dell'architettura fin dalle prime fasi dello sviluppo.

Una struttura corretta permette di distinguere gli errori tecnici dagli errori funzionali.

Un utente che inserisce dati non validi non dovrebbe generare necessariamente un errore applicativo. Al contrario,un database irraggiungibile o un servizio esterno non disponibile rappresentano condizioni che devono essere registrate e gestite.

Questa distinzione permette di costruire applicazioni più prevedibili e più semplici da mantenere.

Conclusione

La gestione degli errori PHP richiede molto più di un semplice try/catch. Un'applicazione affidabile deve utilizzare correttamente Throwable,exception handler,error handler,logging,stack trace e strumenti di debugging,distinguendo chiaramente tra ambiente di sviluppo e produzione.

Durante lo sviluppo,strumenti come Xdebug permettono di analizzare l'esecuzione del codice attraverso breakpoint e debugging step by step. In produzione,invece,la priorità deve essere registrare informazioni sufficientemente dettagliate nei log senza esporre all'utente dati tecnici sensibili.

Anche database,API,PHP-FPM e web server devono essere considerati all'interno dello stesso processo diagnostico. Un errore applicativo può infatti propagarsi attraverso più livelli dell'infrastruttura e produrre sintomi differenti rispetto alla causa originale.

Una corretta strategia di gestione degli errori permette quindi di ridurre i tempi di troubleshooting,migliorare la stabilità del software,proteggere le informazioni interne e rendere più semplice la manutenzione dell'applicazione PHP. In un progetto professionale,logging,exception handling e debugging non sono strumenti accessori,ma componenti fondamentali dell'architettura applicativa.