(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)
set_error_handler — Define uma função de usuário para manipulação de erro
Define uma função de usuário (callback) para lidar
com erros em um script.
Esta função pode ser usada para definir manipuladores de erros customizados em tempo de execução, por exemplo em aplicações que precisem limpar arquivos/dados quando um erro crítico ocorrer, ou no disparo de um erro em resposta a certas condições (usando trigger_error()).
É importante ressaltar que o manipulador padrão de erros do PHP é completamente
ignorado para os tipos de erro especificados por error_levels
a menos que a função de retorno devolva false.
As configurações de error_reporting() não terão efeito e o
manipulador de erro será chamado de qualquer maneira - entretanto, ainda será possível
ler o valor atual de
error_reporting e atuar
apropriadamente.
Note também que é responsabilidade do manipulador para a execução do script se for necessário, chamando-se exit(). Se a função de manipulação de erro simplesmente retornar, a execução do script continuará com a declaração seguinte à que causou o erro.
Os seguintes tipos de erro não podem ser manipulados com uma função definida pelo
usuário: E_ERROR, E_PARSE,
E_CORE_ERROR, E_CORE_WARNING,
E_COMPILE_ERROR,
E_COMPILE_WARNING independentemente de onde eles surgirem, e
a maior parte dos erros E_STRICT originados no arquivo onde a função
set_error_handler() for chamada.
Se erros ocorrerem antes que o script seja executado (ex.: em envios de arquivos), o manipulador customizado de erros não poderá ser chamado já que ainda não estará registrado nesse momento.
callback
Se null for passado, o manipulador será redefinido a seu estado padrão.
Caso contrário, o manipulador é uma função de retorno com a seguinte assinatura:
$errno,$errstr,$errfile = ?,$errline = ?,$errcontext = ?errnoerrno, que conterá o
nível do erro, como um inteiro.
errstrerrstr, que conterá a
mensagem de erro, como uma string.
errfileerrfile,
será passado o nome do arquivo no qual o erro se originou, como uma string.
errlineerrline,
será passado o número da linha onde o erro ocorreu, como um inteiro.
errcontexterrcontext,
será passado um array que aponta para a tabela de símbolos ativa no
ponto onde o erro ocorreu. Em outras palavras, errcontext
conterá um array com cada variável existente no escopo em
que o erro surgiu.
Manipuladores de erro de usuário não devem modificar o contexto de erro.
Este parâmetro tornou-se DESCONTINUADO a partir do PHP 7.2.0, e foi REMOVIDO a partir do PHP 8.0.0. Se a função definir este parâmetro sem um valor padrão, um erro do tipo "too few arguments" será emitido quando ela for chamada.
Se a função retornar false, o manipulador de erros normal continua.
error_levels
Pode ser usado para mascarar a chamada da função
callback da mesma forma que a configuração ini error_reporting
controla quais erros são mostrados. Sem a definição desta máscara, a função
callback será chamada para todo erro,
indenpendentemente da configuração de error_reporting.
Retorna o manipulador de erro anterior (se existente) como um callable.
Se o manipulador interno for usado, null é retornado.
| Versão | Descrição |
|---|---|
| 8.0.0 |
errcontext foi removido e não mais será passado para chamadas de retorno de usuário.
|
| 7.2.0 |
errcontext foi descontinuado. O uso deste parâmetro agora emite uma nota E_DEPRECATED.
|
Exemplo #1 Manipulação de erro com set_error_handler() e trigger_error()
O exemplo abaixo mostra a manipulação de exceções internas através de disparo de erros e uso de função definida pelo usuário:
<?php
// função de manipulação de erro
function myErrorHandler($errno, $errstr, $errfile, $errline)
{
if (!(error_reporting() & $errno)) {
// Este código de erro não está incluído em error_reporting, então será
// passado ao manipulador padrão de erros do PHP
return false;
}
// $errstr pode precisar de escape:
$errstr = htmlspecialchars($errstr);
switch ($errno) {
case E_USER_ERROR:
echo "<b>Meu ERRO</b> [$errno] $errstr<br />\n";
echo " Erro fatal na linha $errline no arquivo $errfile";
echo ", PHP " . PHP_VERSION . " (" . PHP_OS . ")<br />\n";
echo "Abortando...<br />\n";
exit(1);
case E_USER_WARNING:
echo "<b>Meu ALERTA</b> [$errno] $errstr<br />\n";
break;
case E_USER_NOTICE:
echo "<b>Minha NOTA</b> [$errno] $errstr<br />\n";
break;
default:
echo "Tipo de erro desconhecido: [$errno] $errstr<br />\n";
break;
}
/* Não executa o manipulador interno do PHP */
return true;
}
// função para testar a manipulação de erro
function scale_by_log($vect, $scale)
{
if (!is_numeric($scale) || $scale <= 0) {
trigger_error("log(x) para x <= 0 é indefinido, foi usado: escala = $scale", E_USER_ERROR);
}
if (!is_array($vect)) {
trigger_error("Vetor de entrada incorreto, esperado array de valores", E_USER_WARNING);
return null;
}
$temp = array();
foreach($vect as $pos => $value) {
if (!is_numeric($value)) {
trigger_error("Valor na posição $pos não é um número, usando 0 (zero)", E_USER_NOTICE);
$value = 0;
}
$temp[$pos] = log($scale) * $value;
}
return $temp;
}
// define para o manipulador de erro de usuário
$old_error_handler = set_error_handler("myErrorHandler");
// dispara alguns erros, primeiro define um array misto com um item não numérico
echo "vetor a\n";
$a = array(2, 3, "foo", 5.5, 43.3, 21.11);
print_r($a);
// agora gera um segundo array
echo "----\nvetor b - uma nota (b = log(PI) * a)\n";
/* Valor na posição $pos não é um número, usando 0 (zero) */
$b = scale_by_log($a, M_PI);
print_r($b);
// isto é um problema, passando uma string ao invés de um array
echo "----\nvetor c - um alerta\n";
/* Vetor de entrada incorreto, esperado array de valores */
$c = scale_by_log("not array", 2.3);
var_dump($c); // NULL
// aqui um erro crítico, log de zero ou número negativo não é definido
echo "----\nvetor d - erro fatal\n";
/* log(x) para x <= 0 é indefinido, foi usado: escala = $scale" */
$d = scale_by_log($a, -2.5);
var_dump($d); // Nunca alcançado
?>O exemplo acima produzirá algo semelhante a:
vetor a
Array
(
[0] => 2
[1] => 3
[2] => foo
[3] => 5.5
[4] => 43.3
[5] => 21.11
)
----
vetor b - uma nota (b = log(PI) * a)
<b>Minha NOTA</b> [1024] Valor na posição 2 não é um número, usando 0 (zero)<br />
Array
(
[0] => 2.2894597716988
[1] => 3.4341896575482
[2] => 0
[3] => 6.2960143721717
[4] => 49.566804057279
[5] => 24.165247890281
)
----
vetor c - um alerta
<b>Meu ALERTA</b> [512] Vetor de entrada incorreto, esperado array de valores<br />
NULL
----
vetor d - erro fatal
<b>Meu ERRO</b> [256] log(x) para x <= 0 é indefinido, foi usado: escala = -2.5<br />
Erro fatal na linha 35 no arquivo trigger_error.php, PHP 5.2.1 (FreeBSD)<br />
Abortando...<br />