Comprendere il metodo Exception::getLine() in PHP

Quando qualcosa va storto in PHP, la prima cosa di cui di solito hai bisogno è sapere dove è andato storto. Il metodo Exception::getLine() risponde esattamente a questa domanda: ti indica il numero di riga in cui è stato creato un oggetto eccezione. Abbinato a getMessage() e getFile(), ti fornisce un preciso "cosa, dove" per ogni errore che intercetti — il che è il fondamento di un logging e un debugging efficaci.

Questa pagina tratta la firma del metodo, cosa misura esattamente, un esempio completo ed eseguibile, e le insidie comuni in cui le persone incappano.

Sintassi

final public Exception::getLine(): int

Il metodo non accetta argomenti e restituisce un int. È definito sulla classe base Exception, quindi ogni eccezione built-in (RuntimeException, InvalidArgumentException, TypeError e così via) e ogni eccezione personalizzata che scrivi la eredita. Poiché è dichiarato final, non puoi sovrascriverlo in una sottoclasse.

Cosa significa "riga"

Questa è la cosa più importante da capire: getLine() restituisce la riga in cui l'oggetto eccezione è stato costruito (il sito di new Exception(...) / throw new ...), non la riga del problema sottostante e non la riga in cui è stata catturata.

Quindi se il tuo codice chiama una funzione che internamente lancia un'eccezione, getLine() punta all'istruzione throw all'interno di quella funzione — non alla tua chiamata. Per tracciare il percorso completo dalla tua chiamata fino al throw, usa invece getTrace() o getTraceAsString().

Un esempio completo ed eseguibile

L'esempio seguente definisce una funzione che lancia un'eccezione quando un file è mancante, poi cattura l'eccezione e riporta la posizione:

<?php

function readFileContents(string $path): string
{
    if (!file_exists($path)) {
        throw new Exception("File not found: $path"); // this is line 6
    }

    return file_get_contents($path);
}

try {
    echo readFileContents('/no/such/file.txt');
} catch (Exception $e) {
    echo "Error on line " . $e->getLine() . ": " . $e->getMessage();
}

Output:

Error on line 6: File not found: /no/such/file.txt

Nota che la riga riportata è 6 — l'istruzione throw all'interno di readFileContents() — anche se la chiamata che l'ha innescata si trova alla riga 13. Questa è la regola "sito di costruzione, non sito di chiamata" in azione.

Combinare getLine() con getFile()

Un numero di riga da solo è ambiguo in un progetto multi-file, quindi nel codice reale lo si stampa quasi sempre insieme al nome del file ottenuto da getFile():

<?php

try {
    $age = -5;

    if ($age < 0) {
        throw new InvalidArgumentException("Age cannot be negative");
    }
} catch (Exception $e) {
    printf(
        "[%s] %s (line %d in %s)\n",
        get_class($e),
        $e->getMessage(),
        $e->getLine(),
        basename($e->getFile())
    );
}

Output (il nome del file dipende da come chiami lo script):

[InvalidArgumentException] Age cannot be negative (line 5 in script.php)

Qui getLine() restituisce 5, la riga del throw all'interno del blocco try. Catturare Exception funziona per InvalidArgumentException perché ogni tipo di eccezione alla fine estende Exception.

Quando usarlo

• Logging. Scrivi getLine() e getFile() nelle tue voci di log in modo che un messaggio privo di stack trace sia comunque tracciabile.
• Pagine di errore personalizzate. In un ambiente di sviluppo potresti mostrare la riga al developer; in produzione, registrala ma mostra all'utente un messaggio generico.
• Re-wrapping delle eccezioni. Quando intercetti un'eccezione di basso livello e rilanci una specifica del dominio, registra il getLine()/getFile() originale (o concatena con getPrevious()) in modo che la causa radice non vada persa.

Insidie comuni

• Aspettarsi il sito di chiamata. Come mostrato sopra, getLine() indica la posizione del throw, non dove hai chiamato il codice che lancia. Usa un trace per il percorso completo.
• Leggerlo senza catturare. getLine() è un metodo di istanza — puoi chiamarlo solo su un oggetto eccezione di cui hai un riferimento, tipicamente l'$e di un blocco catch.
• Confonderlo con getCode(). getCode() restituisce il codice numerico dell'eccezione, un valore non correlato che imposti alla costruzione dell'eccezione; non ha nulla a che fare con i numeri di riga.

Conclusione

Exception::getLine() restituisce il numero di riga intero in cui è stata creata un'eccezione — un'informazione di debug piccola ma essenziale. Usato insieme a getMessage(), getFile() e uno stack trace completo, ti permette di individuare e registrare gli errori con precisione. Per una visione d'insieme su come lanciare e catturare, consulta la guida alle eccezioni PHP.

Pratica