error_log()

Registrazione degli errori PHP con la funzione Error Log

Stampare gli errori sullo schermo con echo o var_dump() va bene durante lo sviluppo di una funzionalità, ma è lo strumento sbagliato in produzione: l'output a schermo è visibile ai visitatori, va perso nelle chiamate AJAX e scompare nel momento in cui la richiesta termina. La funzione integrata error_log() risolve questo problema inviando un messaggio in una destinazione duratura — un file di log, un'email o il logger del sistema operativo — in modo da poterlo consultare in seguito.

Questa guida spiega cosa fa error_log(), illustra ogni parametro con esempi eseguibili e tratta le insidie (newline finali, la direttiva ini error_log, cosa non registrare) che creano problemi nei progetti reali.

Cosa fa la funzione error_log()

error_log() scrive un singolo messaggio in una destinazione a scelta. Non attiva il meccanismo di gestione degli errori di PHP, non modifica il codice di uscita e non interrompe lo script — si limita a registrare testo. Il valore restituito è un bool: true in caso di successo, false se il messaggio non può essere scritto (ad esempio, il file di log non è scrivibile).

Poiché si tratta semplicemente di "aggiungi questa stringa da qualche parte", error_log() è il modo più semplice per lasciare tracce nel codice che viene eseguito senza che uno sviluppatore stia guardando — cron job, worker in coda, webhook e qualsiasi richiesta in produzione.

Firma della funzione

error_log(
    string $message,
    int $message_type = 0,
    ?string $destination = null,
    ?string $additional_headers = null
): bool

Il comportamento predefinito: registrazione nella destinazione configurata di PHP

La chiamata più comune passa solo il messaggio e lascia che PHP lo instradi verso la destinazione configurata per gli errori del server (la direttiva ini error_log, o il logger SAPI/sistema se non è impostata):

<?php

error_log("Payment gateway returned an unexpected status code");

È esattamente la stessa destinazione in cui vanno già gli avvisi e le notice non gestiti, quindi i messaggi manuali si trovano accanto a quelli propri di PHP. Per vedere la destinazione corrente durante l'esecuzione, leggere il valore ini:

<?php

echo ini_get('error_log') ?: '(SAPI / system default)';

Registrazione su un file specifico (tipo 3)

Il tipo 3 aggiunge il messaggio in coda a un file specificato in $destination. È la modalità principale per i log specifici dell'applicazione:

<?php

$message = "Error: Unable to connect to the database";
error_log($message, 3, "/var/log/php-errors.log");

A differenza del tipo 0, il tipo 3 scrive il messaggio esattamente com'è — nessun timestamp, nessuna severità e, soprattutto, nessuna newline finale. Se si dimentica la newline, ogni chiamata si concatena su un'unica riga:

<?php

$log = sys_get_temp_dir() . "/app.log";
error_log("first", 3, $log);
error_log("second", 3, $log);
echo file_get_contents($log); // firstsecond

Aggiungere PHP_EOL manualmente (e di solito anche un timestamp) in modo che ogni voce sia una riga leggibile:

<?php

$log = sys_get_temp_dir() . "/app.log";
$line = date('[Y-m-d H:i:s] ') . "Cache miss for user 42" . PHP_EOL;
error_log($line, 3, $log);

echo file_get_contents($log);
// [2026-06-21 10:00:00] Cache miss for user 42

Tutti i tipi di messaggio

Il tipo 2 (invio tramite socket TCP) esisteva nelle vecchie versioni di PHP ed è stato rimosso in PHP 8; non fare affidamento su di esso.

Invio di email per errori critici (tipo 1)

Per guasti rari e ad alta severità è possibile far inviare un'email a PHP. Usarlo con parsimonia — un errore frequente che si attiva a ogni richiesta può intasare una casella di posta:

<?php

error_log(
    "FATAL: order processor crashed",
    1,
    "[email protected]",
    "From: [email protected]\r\n"
);

In produzione, una libreria di logging che raggruppa e limita la frequenza degli avvisi è più adatta rispetto all'invio di email a ogni chiamata.

Un pattern realistico di cattura e registrazione

Nel codice applicativo di solito si registra all'interno di un blocco catch, si registra contesto sufficiente per riprodurre il problema e poi si mostra all'utente un messaggio generico:

<?php

function chargeCustomer(int $cents): bool
{
    if ($cents <= 0) {
        throw new InvalidArgumentException("Amount must be positive, got $cents");
    }
    // ... real charge logic ...
    return true;
}

try {
    chargeCustomer(-5);
} catch (Throwable $e) {
    error_log(sprintf(
        "[%s] %s in %s:%d",
        date('Y-m-d H:i:s'),
        $e->getMessage(),
        $e->getFile(),
        $e->getLine()
    ));
    echo "Sorry, we couldn't process your payment.";
}

Il messaggio dettagliato va nel log; il visitatore vede solo la riga amichevole. Questa separazione è l'intera ragion d'essere di error_log().

Insidie comuni

• Nessuna newline con il tipo 3. Aggiungere PHP_EOL manualmente altrimenti le voci si concatenano.
• La direttiva ini error_log imposta la destinazione predefinita. Quando si omettono $message_type/$destination, il messaggio va dove punta ini_get('error_log'). Su una nuova installazione CLI potrebbe essere stderr; su un server web potrebbe essere un file specifico.
• Il file deve essere scrivibile dal processo PHP. Un valore di ritorno false indica spesso un problema di permessi sulla directory o sul file.
• display_errors e error_log sono indipendenti. Disabilitare la visualizzazione degli errori a schermo non interrompe la registrazione, e viceversa — controllarli separatamente.
• Non registrare mai segreti. Password, chiavi API, numeri di carte di credito completi e token di sessione non devono mai raggiungere un file di log. Oscurarli prima di chiamare error_log().

Funzioni correlate

• set_error_handler() — instrada gli avvisi e le notice propri di PHP attraverso il proprio codice in modo da poter chiamare error_log() in modo coerente.
• set_exception_handler() — cattura e registra le eccezioni altrimenti non gestite in un unico punto.
• trigger_error() — genera un errore a livello utente che il gestore degli errori (e quindi la registrazione) raccoglierà.
• error_reporting() — scegliere quali livelli di errore vengono segnalati in primo luogo.
• syslog() — invia messaggi direttamente al logger di sistema con un livello di severità.

Conclusione

error_log() è il modo più semplice e duraturo per registrare cosa è andato storto nel codice che nessuno sviluppatore sta monitorando. Usare il tipo 3 con un timestamp e PHP_EOL per i file di log dell'applicazione, ricorrere alla destinazione predefinita per affiancarsi agli errori propri di PHP e riservare l'email (tipo 1) per eventi genuinamente critici. Abbinarlo a set_error_handler() e set_exception_handler() per catturare tutto in un unico punto — e non scrivere mai segreti in un log.

Esercitazione