Entendendo o Método Exception::getLine() no PHP

Quando algo dá errado no PHP, a primeira coisa que você geralmente precisa saber é onde deu errado. O método Exception::getLine() responde exatamente a isso: ele informa o número da linha em que um objeto de exceção foi criado. Combinado com getMessage() e getFile(), ele fornece um "o quê, onde" preciso para qualquer erro que você capture — o que é a base de um logging e depuração úteis.

Esta página cobre a assinatura do método, o que ele mede de fato, um exemplo completo e executável, e as armadilhas comuns que pegam as pessoas desprevenidas.

Sintaxe

final public Exception::getLine(): int

O método não recebe argumentos e retorna um int. Ele é definido na classe base Exception, portanto toda exceção embutida (RuntimeException, InvalidArgumentException, TypeError, e assim por diante) e toda exceção personalizada que você escrever a herda. Por ser declarado final, você não pode sobrescrevê-lo em uma subclasse.

O que "linha" realmente significa

Este é o ponto mais importante a entender: getLine() retorna a linha onde o objeto de exceção foi construído (o local do new Exception(...) / throw new ...), não a linha do problema subjacente e não a linha onde ele foi capturado.

Portanto, se seu código chama uma função que internamente lança uma exceção, getLine() aponta para a instrução throw dentro dessa função — não para a sua chamada. Para rastrear o caminho completo desde a sua chamada até o lançamento, use getTrace() ou getTraceAsString().

Um exemplo completo e executável

O exemplo abaixo define uma função que lança uma exceção quando um arquivo está ausente, depois captura a exceção e reporta a localização:

<?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();
}

Saída:

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

Observe que a linha reportada é 6 — a instrução throw dentro de readFileContents() — mesmo que a chamada que a disparou esteja na linha 13. Essa é a regra do "local de construção, não o local da chamada" em ação.

Combinando getLine() com getFile()

Um número de linha isolado é ambíguo em um projeto com múltiplos arquivos, então no código real você quase sempre o imprime junto com o nome do arquivo obtido de 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())
    );
}

Saída (o nome do arquivo depende de como você nomeia o script):

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

Aqui getLine() retorna 5, a linha do throw dentro do bloco try. Capturar Exception funciona para InvalidArgumentException porque todo tipo de exceção estende Exception em última instância.

Quando usá-lo

• Logging. Escreva getLine() e getFile() nas suas entradas de log para que uma mensagem sem stack trace ainda possa ser rastreada.
• Páginas de erro personalizadas. Em um ambiente de desenvolvimento, você pode exibir a linha para o desenvolvedor; em produção, registre-a mas mostre ao usuário uma mensagem genérica.
• Reempacotamento de exceções. Quando você captura uma exceção de baixo nível e relança uma exceção específica de domínio, registre o getLine()/getFile() original (ou encadeie com getPrevious()) para que a causa raiz não seja perdida.

Armadilhas comuns

• Esperar o local da chamada. Como mostrado acima, getLine() é o local do lançamento, não onde você chamou o código que lança. Use um trace para o caminho completo.
• Lê-lo sem capturar. getLine() é um método de instância — você só pode chamá-lo em um objeto de exceção ao qual tem uma referência, tipicamente o $e de um bloco catch.
• Confundi-lo com getCode(). getCode() retorna o código numérico da exceção, um valor não relacionado que você define ao construir a exceção; ele não tem nada a ver com números de linha.

Conclusão

Exception::getLine() retorna o número de linha inteiro onde uma exceção foi criada — uma informação pequena mas essencial para depuração. Usada em conjunto com getMessage(), getFile(), e um stack trace completo, ela permite localizar e registrar erros com precisão. Para uma visão mais ampla sobre lançamento e captura, consulte o guia de exceções PHP.

Prática