getFile()

Introduzione

getFile() è un metodo integrato della classe Exception di PHP (e di ogni classe che la estende, inclusa Error). Quando viene lanciata un'eccezione, PHP registra il percorso del file sorgente in cui è stata eseguita l'istruzione throw. getFile() restituisce quel percorso in modo da poter individuare con precisione dove qualcosa è andato storto — informazione preziosa quando un errore risale attraverso molti livelli di codice.

Questa pagina illustra cosa restituisce getFile(), in cosa differisce dai metodi correlati e come combinarlo con getLine() e getMessage() per costruire log degli errori leggibili.

Sintassi

public string Exception::getFile(): string

getFile() è dichiarato final nella classe base Exception, quindi non è possibile sovrascriverlo nelle proprie sottoclassi di eccezione — il valore viene sempre impostato da PHP nel momento in cui l'oggetto viene costruito.

Parametri

getFile() non accetta parametri.

Valore restituito

Una string contenente il percorso assoluto del file in cui è stata lanciata l'eccezione — ad esempio /var/www/app/src/Order.php, non solo Order.php. Se si desidera solo il nome del file, è possibile racchiudere il risultato in basename().

Il percorso riflette dove l'oggetto eccezione è stato creato (il punto di throw/new), non dove è stato catturato. Questa distinzione è importante quando si rilanciano eccezioni tra file diversi.

Esempio di base

L'esempio seguente lancia un'eccezione e poi riporta esattamente da dove proviene:

<?php

try {
    throw new Exception('Database connection failed');
} catch (Exception $e) {
    echo 'Message: ', $e->getMessage(), "\n";
    echo 'File: ', $e->getFile(), "\n";
    echo 'Line: ', $e->getLine(), "\n";
}

Output (il percorso dipende da dove si trova lo script):

Message: Database connection failed
File: /var/www/app/index.php
Line: 4

Si noti che getFile() riporta la riga 4 tramite getLine() — la riga del throw, non del catch.

Costruire una riga di log leggibile

Nelle applicazioni reali il percorso del file è solitamente lungo, quindi è comune ridurlo con basename() e assemblare un unico messaggio di log compatto:

<?php

function processOrder(int $id): void
{
    throw new RuntimeException("Order #$id is invalid");
}

try {
    processOrder(42);
} catch (RuntimeException $e) {
    echo 'Error in ' . basename($e->getFile())
        . ' (line ' . $e->getLine() . '): '
        . $e->getMessage() . "\n";
}

Output:

Error in index.php (line 5): Order #42 is invalid

Anche se l'eccezione è stata catturata all'interno del blocco try, getFile() e getLine() puntano alla riga 5 — l'istruzione throw all'interno di processOrder().

Quando usarlo

• Logging e monitoraggio. Combinare getFile() con getLine() e getMessage() per scrivere voci di log che indicano esattamente dove guardare.
• Debug di chiamate profondamente annidate. Quando un'eccezione risale attraverso diverse funzioni o file, getFile() indica l'origine reale, non il punto di cattura.
• Pagine di errore personalizzate (in sviluppo). Visualizzare il file e la riga su una schermata di debug — ma non esporre mai percorsi assoluti del server agli utenti finali in produzione.

Per avere un quadro completo di un errore si abbina spesso a getTrace() o getTraceAsString(), che mostrano l'intero call stack anziché una singola posizione.

Metodi correlati

Vedere getMessage(), getLine() e getCode() per ciascuno di questi. Per capire come l'intero meccanismo si incastra, leggere il capitolo sulle eccezioni PHP e il riferimento try/catch.

Conclusione

getFile() è una parte piccola ma essenziale del sistema di eccezioni di PHP: risponde alla domanda "quale file ha lanciato questo errore?". Insieme a getLine() e getMessage() trasforma un generico fallimento in un rapporto preciso e utilizzabile — la base di un buon logging e di un debug rapido.

Esercitazione