getTrace()

PHP getTrace()

Exception::getTrace() retorna o stack trace de uma exceção como um array. Cada elemento descreve uma chamada de função ou método que estava na pilha de chamadas no momento em que a exceção foi lançada, ordenada do ponto de lançamento para fora. É uma das ferramentas mais úteis para descobrir onde e como um erro ocorreu.

Esta página aborda o que getTrace() retorna, a estrutura de cada frame do trace e como difere do mais familiar getTraceAsString(). O método é definido na interface base Throwable, portanto está disponível em todo objeto Exception e Error.

public Exception::getTrace(): array

Não recebe argumentos e retorna um array indexado. O frame 0 é a chamada mais interna (a função que efetivamente lançou a exceção), e os índices crescem em direção ao chamador mais externo.

Exemplo rápido

O script a seguir lança uma exceção a partir de uma chamada aninhada e imprime cada frame do trace:

<?php

function readConfig($path) {
    return parseFile($path);
}

function parseFile($path) {
    throw new Exception("Cannot read file: $path");
}

try {
    readConfig('/etc/app.conf');
} catch (Exception $e) {
    $trace = $e->getTrace();
    echo "Number of frames: " . count($trace) . "\n";
    foreach ($trace as $i => $frame) {
        echo "#$i {$frame['function']}() called in {$frame['file']} on line {$frame['line']}\n";
    }
}

Saída:

Number of frames: 2
#0 parseFile() called in /path/to/script.php on line 4
#1 readConfig() called in /path/to/script.php on line 12

Observe que o frame da função que lançou a exceção (parseFile) reporta a linha onde foi chamada (linha 4, dentro de readConfig), não a linha do próprio throw. A linha do lançamento está disponível separadamente via getLine() e getFile().

O que cada frame do trace contém

Cada frame é um array associativo. As chaves mais úteis são:

Este script inspeciona um único frame completo:

<?php

function divide($a, $b) {
    if ($b === 0) {
        throw new InvalidArgumentException('Division by zero');
    }
    return $a / $b;
}

try {
    divide(10, 0);
} catch (Exception $e) {
    print_r($e->getTrace()[0]);
}

Saída:

Array
(
    [file] => /path/to/script.php
    [line] => 11
    [function] => divide
    [args] => Array
        (
            [0] => 10
            [1] => 0
        )

)

Nota de segurança: a entrada args contém os valores reais dos argumentos, que podem incluir senhas, tokens ou outros dados sensíveis. Nunca exponha um array bruto de getTrace() aos usuários finais — registre-o no lado do servidor. A configuração INI zend.exception_ignore_args do PHP (ativa por padrão desde o PHP 7.4) remove args para evitar vazamento de dados sensíveis; se você não vir uma chave args, é por isso.

getTrace() vs getTraceAsString()

getTrace() fornece o array bruto para que você possa formatá-lo, filtrá-lo ou serializá-lo como desejar. Se você quiser apenas uma string legível por humanos, use getTraceAsString(), que retorna as mesmas informações pré-formatadas:

<?php

try {
    throw new RuntimeException('Something broke');
} catch (Throwable $e) {
    echo $e->getTraceAsString();
}

Use a forma de array quando quiser percorrer os frames programaticamente (por exemplo, construir um relatório de erro personalizado ou enviar dados estruturados para um serviço de log), e a forma de string para exibição rápida ou linhas de log.

Onde getTrace() se encaixa na API de exceções

getTrace() é um dos vários acessores somente-leitura disponíveis em toda exceção. Eles são mais poderosos quando usados em conjunto dentro de um bloco catch:

• getMessage() — a mensagem de erro legível por humanos.
• getCode() — o código de erro numérico.
• getFile() e getLine() — onde a exceção foi lançada.
• getTraceAsString() — o trace como uma string.
• getPrevious() — a exceção encadeada, se houver.

Para uma visão mais ampla sobre lançar e capturar exceções, consulte throw, try e a classe Exception.

Boas Práticas para Tratamento de Exceções em PHP

Para garantir que seu código seja manutenível e fácil de depurar, é importante seguir boas práticas ao lidar com exceções em PHP. Aqui estão algumas dicas para ter em mente:

1. Use mensagens de exceção significativas.

Ao lançar uma exceção, certifique-se de que a mensagem seja informativa e útil. Ela deve explicar o que deu errado e como corrigi-lo. Por exemplo:

<?php

if ($someCondition) {
  throw new Exception('Invalid input: the email address is not valid.');
}

2. Capture apenas as exceções que você pode tratar.

Ao capturar exceções, é importante capturar apenas aquelas que você pode tratar. Se você capturar uma exceção que não pode tratar, poderá acabar ocultando o problema real e tornando a depuração mais difícil. Por exemplo:

<?php

try {
  // Some code that may throw an exception.
} catch (InvalidArgumentException $e) {
  // Handle the invalid argument exception.
} catch (Exception $e) {
  // Handle all other exceptions.
}

3. Registre as exceções.

Registrar exceções pode ajudá-lo a diagnosticar problemas e solucionar questões. É uma boa ideia registrar exceções em um arquivo ou banco de dados para que você possa revisá-las posteriormente. Por exemplo:

<?php

try {
  // Some code that may throw an exception.
} catch (Exception $e) {
  error_log($e->getMessage(), 0);
}

4. Use hierarquias de exceções.

Usar hierarquias de exceções pode ajudá-lo a organizar seu código e facilitar a captura de tipos específicos de exceções. Por exemplo, você pode criar uma classe DatabaseException que estende a classe Exception, e então lançar essa exceção quando um erro de banco de dados ocorrer. Você poderia então capturar apenas instâncias de DatabaseException ao tratar erros de banco de dados.

Conclusão

O tratamento de exceções é um aspecto crítico da programação em PHP, e o método getTrace() é uma ferramenta valiosa para depurar e solucionar problemas com exceções. Ao retornar um backtrace do contexto de execução, você pode identificar onde uma exceção ocorreu e como foi disparada.

Neste guia, cobrimos os fundamentos do tratamento de exceções em PHP, incluindo como lançar e capturar exceções, e boas práticas para usar exceções de forma eficaz. Também exploramos o método getTrace() e como ele pode ajudá-lo a diagnosticar e corrigir erros em seu código.

Seguindo essas boas práticas e aproveitando o método getTrace(), você pode escrever código PHP robusto, confiável e fácil de manter. O tratamento de exceções pode parecer um detalhe pequeno, mas pode fazer uma grande diferença na qualidade e usabilidade do seu código.

Practice