error_get_last()

O tratamento de erros é uma parte importante da programação em PHP, pois erros podem ocorrer a qualquer momento durante a execução. A função error_get_last() é uma função nativa do PHP que permite inspecionar o erro mais recente registrado pelo PHP — seu tipo, mensagem, arquivo e linha — para que você possa registrá-lo ou reagir a ele no código. Este capítulo explica o que a função retorna, quando ela retorna null, os tipos de erros que ela captura e não captura, e como usá-la corretamente no PHP moderno.

O que error_get_last() retorna

error_get_last() não recebe argumentos e retorna informações sobre o último erro que o PHP levantou durante a requisição atual. O valor de retorno é uma de duas coisas:

• Um array associativo com quatro chaves, se um erro tiver ocorrido.
• null, se nenhum erro tiver sido registrado ainda.

O array tem a seguinte estrutura:

[
  'type'    => 2,                       // int: the error level (E_WARNING here)
  'message' => 'fopen(...): ...',       // string: the error description
  'file'    => '/path/to/script.php',   // string: file where the error happened
  'line'    => 12,                      // int: line number where it happened
]

O elemento type é um inteiro correspondente a uma das constantes de nível de erro do PHP — por exemplo E_WARNING (2), E_NOTICE (8), E_USER_WARNING (512) ou E_DEPRECATED. Consulte a referência de erros do PHP para a lista completa.

O que ela captura e o que não captura

Esta é a parte em que as pessoas erram, por isso vale a pena ser preciso:

• Ela captura erros, avisos, notificações e depreciações reportados — tudo que flui pelo mecanismo normal de erros do PHP, incluindo os levantados com trigger_error().
• Ela não captura exceções. No PHP moderno (7.0+), muitas falhas lançam exceções em vez de levantar erros — por exemplo, divisão e módulo por zero lançam DivisionByZeroError, não um aviso. Esses casos devem ser tratados com try/catch, e error_get_last() não os verá.
• Ela só vê erros que são efetivamente reportados. Se um nível de erro for filtrado por error_reporting(), ele não aparecerá. Ative error_reporting(E_ALL) durante a depuração para que nada seja descartado silenciosamente.

Por causa disso, error_get_last() é mais útil logo após uma função nativa que sinaliza falha por meio de um aviso (como fopen(), file_get_contents() ou unlink()), e dentro de uma função de desligamento personalizada para capturar um erro fatal que encerrou a requisição.

Exemplos

Lendo o último aviso de um fopen() que falhou

Funções como fopen() retornam false e levantam um E_WARNING quando falham. O operador @ suprime a exibição do aviso, mas ainda permite que error_get_last() o leia:

<?php
error_reporting(E_ALL);

$handle = @fopen("/no/such/file.txt", "r");

if ($handle === false) {
    $error = error_get_last();
    echo "Type:    " . $error['type']    . "\n";
    echo "Message: " . $error['message'] . "\n";
    echo "Line:    " . $error['line']    . "\n";
}
?>

Saída:

Type:    2
Message: fopen(/no/such/file.txt): Failed to open stream: No such file or directory
Line:    4

O type é 2, que é o valor da constante E_WARNING, e a mensagem vem diretamente do fopen().

Capturando um erro que você mesmo levanta

Você pode registrar seu próprio erro com trigger_error() e depois lê-lo:

<?php
error_reporting(E_ALL);
ini_set('display_errors', '0');

trigger_error("Invalid configuration value", E_USER_WARNING);

$error = error_get_last();
echo "Message: " . $error['message'] . "\n";
echo "Type:    " . $error['type'] . "\n"; // 512 = E_USER_WARNING
?>

Saída:

Message: Invalid configuration value
Type:    512

Quando nenhum erro ocorreu

Se nada deu errado ainda, a função retorna null, por isso sempre verifique antes de ler as chaves do array:

<?php
$error = error_get_last();

var_dump($error); // NULL — guard against this before using $error['message']
?>

Saída:

NULL

Armadilhas comuns

• Sempre verifique se o resultado é null (if ($error !== null)) antes de acessar $error['message'], ou você vai disparar um novo aviso de "trying to access array offset on null".
• Divisão por zero não é mais um aviso. Use try/catch para DivisionByZeroError; error_get_last() não o reportará.
• Para registro programático em vez de inspeção, considere combinar isso com error_log() ou um manipulador personalizado registrado com set_error_handler().

Conclusão

error_get_last() fornece o tipo, a mensagem, o arquivo e a linha do erro mais recente registrado pelo PHP, ou null se não houver nenhum. Use-a logo após uma função nativa que falha com um aviso, ou dentro de uma função de desligamento — e lembre-se de que exceções (incluindo divisão por zero moderna) precisam de try/catch em vez disso.

Prática