Descrição

set_error_handler(?callable $callback, int $error_levels = E_ALL): ?callable

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.

Parâmetros

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:

handler(
    int $errno,
    string $errstr,
    string $errfile = ?,
    int $errline = ?,
    array $errcontext = ?
): bool

errno: O primeiro parâmetro, errno, que conterá o nível do erro, como um inteiro.
errstr: O segundo parâmetro, errstr, que conterá a mensagem de erro, como uma string.
errfile: Se a função de retorno aceitar um terceiro parâmetro, errfile, será passado o nome do arquivo no qual o erro se originou, como uma string.
errline: Se a função de retorno aceitar um quarto parâmetro, errline, será passado o número da linha onde o erro ocorreu, como um inteiro.
errcontext: Se a função de retorno aceitar um quinto parâmetro, errcontext, 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.
Aviso
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.

Valor Retornado

Retorna o manipulador de erro anterior (se existente) como um callable. Se o manipulador interno for usado, null é retornado.

Registro de Alterações

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.

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`.

Exemplos

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 />

Veja Também

ErrorException
error_reporting() - Define quais erros do PHP são relatados
restore_error_handler() - Restaura a função anterior de gerenciamento de erro
get_error_handler() - Obtém a função de manipulação de erro definida pelo usuário
trigger_error() - Gera uma mensagem a nível de usuário de erro/alerta/nota
Constantes de nível de erro