getFile()

Introdução

getFile() é um método embutido da classe Exception do PHP (e de toda classe que a estende, incluindo Error). Quando uma exceção é lançada, o PHP registra o caminho do arquivo-fonte em que a instrução throw foi executada. getFile() retorna esse caminho para que você possa identificar onde algo deu errado — o que é extremamente útil quando um erro sobe por muitas camadas de código.

Esta página aborda o que getFile() retorna, como ele difere de métodos relacionados, e como combiná-lo com getLine() e getMessage() para criar logs de erros legíveis.

Sintaxe

public string Exception::getFile(): string

getFile() é declarado como final na classe base Exception, portanto não é possível sobrescrevê-lo em suas próprias subclasses de exceção — o valor é sempre definido pelo próprio PHP no momento em que o objeto é construído.

Parâmetros

getFile() não aceita parâmetros.

Valor de retorno

Uma string contendo o caminho absoluto do arquivo em que a exceção foi lançada — por exemplo /var/www/app/src/Order.php, e não apenas Order.php. Se você quiser somente o nome do arquivo, envolva o resultado com basename().

O caminho reflete onde o objeto de exceção foi criado (o ponto do throw/new), e não onde foi capturado. Essa distinção é importante quando você relança exceções entre arquivos.

Exemplo básico

O exemplo abaixo lança uma exceção e informa exatamente de onde ela veio:

<?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";
}

Saída (o caminho depende de onde o script está localizado):

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

Observe que getFile() informa a linha 4 por meio de getLine() — a linha do throw, não do catch.

Construindo uma linha de log legível

Em aplicações reais, o caminho do arquivo costuma ser longo, por isso é comum reduzi-lo com basename() e montar uma única mensagem de log compacta:

<?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";
}

Saída:

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

Mesmo que a exceção tenha sido capturada dentro do bloco try, getFile() e getLine() apontam para a linha 5 — a instrução throw dentro de processOrder().

Quando usar

• Logging e monitoramento. Combine getFile() com getLine() e getMessage() para escrever entradas de log que indicam exatamente onde procurar.
• Depuração de chamadas profundamente aninhadas. Quando uma exceção percorre várias funções ou arquivos, getFile() informa a origem real, não o ponto de captura.
• Páginas de erro personalizadas (em desenvolvimento). Exiba o arquivo e a linha em uma tela de depuração — mas nunca exponha caminhos absolutos do servidor para usuários finais em produção.

Para uma visão completa de um erro, você frequentemente vai combiná-lo com getTrace() ou getTraceAsString(), que mostram toda a pilha de chamadas em vez de um único local.

Métodos relacionados

Consulte getMessage(), getLine() e getCode() para cada um deles. Para entender como todo o mecanismo se encaixa, leia o capítulo sobre exceções PHP e a referência do try/catch.

Conclusão

getFile() é uma parte pequena, mas essencial, do sistema de exceções do PHP: ele responde à pergunta "qual arquivo lançou isso?" Junto com getLine() e getMessage(), transforma uma falha vaga em um relatório preciso e acionável — a base de um bom logging e de uma depuração eficiente.

Prática