Capturar erro fatal no PHP com register_shutdown_function

Página branca, log da aplicação vazio, e o seu try/catch não pegou nada. É esperado: estouro de memory_limit e de max_execution_time não viram exceção no PHP 8.3, viram erro fatal, e erro fatal mata o processo sem passar pelo catch. Quem ainda roda é a função registrada no desligamento.

O handler, no topo do bootstrap

<?php
// bootstrap-fatal.php — inclua ANTES do autoload, sem depender de classe nenhuma
$GLOBALS['reserva'] = str_repeat('x', 512 * 1024);

register_shutdown_function(static function (): void {
    $GLOBALS['reserva'] = null;

    $e = error_get_last();
    $fatais = [E_ERROR, E_PARSE, E_CORE_ERROR, E_COMPILE_ERROR, E_USER_ERROR];
    if ($e === null || !in_array($e['type'], $fatais, true)) {
        return;
    }

    error_log(sprintf('[FATAL] %s em %s:%d', $e['message'], $e['file'], $e['line']));

    if (!headers_sent()) {
        http_response_code(500);
        header('Content-Type: text/plain; charset=utf-8');
    }
    echo "Erro interno. O time já foi avisado.n";
});

O filtro por tipo é obrigatório: o error_get_last() devolve também o último aviso inofensivo, e sem essa checagem o log enche de E_WARNING de fopen sem pista do que derrubou a requisição.

Três pegadinhas

A primeira é a memória: quando o processo morre por estourar o limite, o handler roda com o limite ainda estourado e montar a string do log pode falhar de novo — por isso a reserva alocada na primeira linha e liberada assim que o desligamento começa. A segunda é o E_PARSE: se o erro de sintaxe está no arquivo que registraria o handler, ele nunca chega a existir — daí o registro morar num arquivo separado, incluído antes de tudo.

A terceira confunde muita gente: timeout do PHP e timeout do PHP-FPM são coisas diferentes. O max_execution_time é contador do próprio PHP, dispara erro fatal e o handler roda. Já o request_terminate_timeout do pool é o gerenciador matando o filho a sinal, sem desligamento limpo: sobra Child process exited on signal 15 no log do FPM e um 502 na tela. Se o handler nunca aparece, confira esse valor antes de mexer no código.

Deixe display_errors = Off em produção e confira o destino do error_log: sem php_admin_value[error_log] no pool, a mensagem cai no log do FPM, não no do site.

Dúvidas? Faça um comentário logo abaixo ou envie uma mensagem clicando aqui.

O seu endereço de e-mail não será publicado. Campos obrigatórios são marcados com *