PHP: Gestione degli errori con logging e livello di gravità

Introduzione

Quando un’applicazione PHP cresce, non basta più “mostrare un messaggio di errore” e andare avanti. In un progetto reale è fondamentale registrare gli errori in modo strutturato, così da capire rapidamente cosa è successo, dove è successo e quanto è grave il problema.

Un sotto-argomento molto utile, pratico e spesso sottovalutato è la gestione degli errori con logging basato sul livello di gravità. Invece di salvare tutto nello stesso modo, possiamo distinguere tra:

• notice: informazioni utili ma non critiche;
• warning: situazioni anomale che non bloccano il flusso;
• error: problemi seri che richiedono attenzione;
• critical: errori gravi che possono compromettere l’esecuzione.

Questo approccio è molto efficace perché permette di filtrare i log, intervenire prima sui problemi più importanti e ridurre il rumore nei file di log. In questo tutorial vedremo come costruire un piccolo sistema di logging in PHP che gestisce gli errori con livelli di priorità, usando un file di log e una configurazione semplice da estendere.

Codice completo

<?php
declare(strict_types=1);

/**
 * Esempio di gestione errori con logging basato sul livello di gravità.
 * Il codice intercetta errori PHP, li converte in eccezioni e li registra su file.
 */

class ErrorLogger
{
    private string $logFile;
    private array $levels = [
        E_NOTICE => ´NOTICE´,
        E_USER_NOTICE => ´NOTICE´,
        E_WARNING => ´WARNING´,
        E_USER_WARNING => ´WARNING´,
        E_ERROR => ´ERROR´,
        E_USER_ERROR => ´ERROR´,
        E_PARSE => ´CRITICAL´,
        E_RECOVERABLE_ERROR => ´CRITICAL´,
        E_CORE_ERROR => ´CRITICAL´,
        E_COMPILE_ERROR => ´CRITICAL´,
    ];

    public function __construct(string $logFile)
    {
        $this-

Spiegazione

Vediamo il funzionamento del codice in modo ordinato.

1. La classe ErrorLogger

La classe incapsula la logica di scrittura dei log. Questo è importante perché evita di spargere chiamate a file_put_contents() ovunque nel progetto. Centralizzare il logging rende il codice più pulito e più facile da mantenere.

La proprietà $levels associa i codici di errore PHP a una stringa leggibile. Ad esempio:

• E_WARNING diventa WARNING;
• E_USER_ERROR diventa ERROR;
• E_PARSE diventa CRITICAL.

Questo mapping è utile perché i codici numerici PHP non sono immediatamente leggibili nei file di log.

2. Il metodo log()

Il metodo log() costruisce una riga di log con data, livello, messaggio e contesto opzionale. Il contesto viene serializzato in JSON, così possiamo aggiungere informazioni come file, riga, ID utente o dati della richiesta.

Un esempio di riga generata potrebbe essere:

[2026-07-29 10:15:00] [WARNING] Valore non valido fornito dall’utente | Context: {"severity":512,"file":"/var/www/html/index.php","line":42}

Il parametro LOCK_EX aiuta a ridurre il rischio di scritture simultanee sul file di log quando più richieste arrivano nello stesso momento.

3. Il metodo handlePhpError()

Questo metodo riceve un errore PHP intercettato dal custom error handler. In base alla severità, decide il livello da registrare. In più, per gli errori più gravi, lancia un’ErrorException per interrompere l’esecuzione in modo controllato.

Questa strategia è molto utile perché separa gli errori “gestibili” da quelli realmente critici. Ad esempio, un warning può essere registrato e lasciato proseguire, mentre un fatal-like error merita un blocco immediato.

4. set_error_handler()

Con set_error_handler() diciamo a PHP di usare la nostra funzione personalizzata per gestire gli errori. Questo ci permette di intercettare molte situazioni prima che PHP le mostri direttamente a schermo.

Restituire true significa che l’errore è stato gestito e non serve il comportamento predefinito di PHP.

5. set_exception_handler()

Le eccezioni non catturate vengono gestite da set_exception_handler(). Anche qui registriamo tutto nel log con livello CRITICAL, perché un’eccezione non gestita è quasi sempre un problema serio.

In un’applicazione web, dopo aver registrato l’errore, è buona pratica mostrare all’utente un messaggio generico come “Si è verificato un errore interno”, senza esporre dettagli sensibili.

6. Esempi pratici

Nel codice troviamo tre esempi:

• lettura di una variabile non definita, per simulare un warning/notice;
• trigger_error(..., E_USER_WARNING) per generare un errore controllato;
• trigger_error(..., E_USER_ERROR) per simulare un errore grave.

Questi esempi sono molto utili nei test e nello sviluppo, perché permettono di verificare che il sistema di logging funzioni davvero come previsto.

Best practice

• Non loggare tutto allo stesso livello: distinguere notice, warning, error e critical aiuta a filtrare meglio i problemi.
• Non mostrare dettagli sensibili all’utente: file, stack trace e query SQL devono restare nei log, non nella UI pubblica.
• Usa un formato coerente: data, livello, messaggio e contesto devono avere sempre la stessa struttura.
• Aggiungi contesto utile: URL richiesto, ID utente, metodo HTTP e dati tecnici possono accelerare il debug.
• Proteggi il file di log: assicurati che la directory sia scrivibile dal server web ma non esposta pubblicamente.
• Evita log troppo verbosi in produzione: in produzione è meglio registrare solo ciò che serve davvero.
• Separa errori applicativi e errori di sistema: non tutto deve finire nello stesso file se il progetto è grande.

Riepilogo

Gestire gli errori in PHP con un logging basato sul livello di gravità è una soluzione pratica, ordinata e molto utile nei progetti reali. Ti permette di:

• intercettare gli errori in modo centralizzato;
• classificare i problemi in base alla loro importanza;
• salvare informazioni tecniche utili per il debug;
• mostrare all’utente messaggi più puliti e sicuri;
• migliorare la manutenzione dell’applicazione nel tempo.

Il vero vantaggio di questo approccio è la scalabilità: oggi puoi scrivere su file, domani potrai integrare un servizio esterno, un sistema di monitoraggio o una dashboard di osservabilità, senza dover riscrivere tutta la logica di gestione degli errori.

Approfondisci con risorse ufficiali

• PHP Manual - Error Handling: documentazione ufficiale sulla gestione degli errori in PHP.
• PHP Manual - set_error_handler(): per personalizzare la gestione degli errori.
• PHP Manual - set_exception_handler(): per intercettare eccezioni non gestite.
• PHP Manual - ErrorException: utile per trasformare errori in eccezioni.
• PHP Manual - file_put_contents(): funzione usata per scrivere i log su file.

Se vuoi, nel prossimo passo posso scrivere un tutorial collegato su come integrare questo sistema con Monolog oppure su come registrare stack trace e request context in modo professionale.