Exibir erros no PHP: display_errors e E_ALL

Para mostrar os erros do PHP, coloque estas linhas no topo do script: ini_set('display_errors', '1'); e error_reporting(E_ALL);. A primeira faz o PHP imprimir mensagens de erro, a segunda faz ele relatar todos os tipos de erro, incluindo avisos e depreciações.

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

Com isso no lugar, um erro como ler uma variável que nunca foi definida imprime uma mensagem com o arquivo e o número da linha, em vez de falhar em silêncio:

Warning: Undefined variable $total in /home/index.php on line 7

error_reporting() chamado sem argumento retorna a configuração atual como número. Clique em Run para definir um nível e decodificá-lo de volta em nomes:

<?php
error_reporting(E_ALL & ~E_DEPRECATED);
$level = error_reporting();

echo "Current level: $level (E_ALL is " . E_ALL . ")\n";

foreach (get_defined_constants(true)['Core'] as $name => $value) {
    if (str_starts_with($name, 'E_') && $name !== 'E_ALL') {
        echo str_pad($name, 20), ($level & $value) ? "reported" : "off", "\n";
    }
}

Cada tipo de erro é um bit, então E_ALL & ~E_DEPRECATED significa "tudo menos depreciações". Mude a primeira linha para error_reporting(E_ERROR | E_WARNING); e rode de novo.

Exibir erros no php.ini

Uma configuração no script só vale depois que o script começa a rodar. Para mostrar erros em todos os scripts, incluindo erros de sintaxe, altere o php.ini (encontre-o com php --ini):

; Development
display_errors = On
display_startup_errors = On
error_reporting = E_ALL

Reinicie o Apache ou o PHP-FPM depois de editar. O servidor embutido php -S e a linha de comando leem o arquivo a cada inicialização. Em hospedagem compartilhada sem acesso ao php.ini, o Apache com mod_php também aceita linhas no .htaccess:

php_flag display_errors on
php_value error_reporting -1

-1 liga todos os bits, o que equivale a E_ALL.

Os níveis de erro

O PHP 8.0 transformou muitos avisos antigos em exceções: dividir por zero com / e passar o tipo errado para uma função nativa agora lançam uma subclasse de Error, do mesmo jeito que chamar uma função indefinida faz desde o PHP 7. Você pode capturar os três:

<?php
$attempts = [
    fn() => 10 / 0,
    fn() => strlen([]),
    fn() => undefinedFunction(),
];

foreach ($attempts as $attempt) {
    try {
        $attempt();
    } catch (Throwable $e) {
        echo get_class($e), ": ", $e->getMessage(), "\n";
    }
}

Exceções são explicadas em try e catch. Avisos, notices e depreciações continuam passando pelo sistema de relatório de erros descrito aqui.

Registrar erros em log em vez de exibi-los

Num site no ar, os visitantes nunca devem ver mensagens de erro: elas revelam caminhos, SQL e código. Escreva-as num arquivo de log:

; Production
display_errors = Off
log_errors = On
error_log = /var/log/php/app-errors.log
error_reporting = E_ALL

Mantenha error_reporting = E_ALL em produção. Reduzir esse valor não faz os erros sumirem, só impede que você fique sabendo deles. Suas próprias mensagens podem ir para o mesmo log com error_log():

<?php
error_log("Payment failed for order 1042");

Depois acompanhe o arquivo enquanto testa: tail -f /var/log/php/app-errors.log.

Transformar avisos em exceções com set_error_handler

set_error_handler troca o tratamento padrão do PHP para avisos, notices e depreciações por uma função sua. Um padrão comum converte cada um deles numa ErrorException, então uma chave de array esquecida para o código como qualquer outra exceção e pode ser capturada:

<?php
set_error_handler(function (int $severity, string $message, string $file, int $line): bool {
    throw new ErrorException($message, 0, $severity, $file, $line);
});

$prices = ['bread' => 4.5, 'milk' => 1.2];

try {
    echo "Bread costs {$prices['bread']}\n";
    echo "Cheese costs {$prices['cheese']}\n";
} catch (ErrorException $e) {
    echo "Caught: ", $e->getMessage(), " on line ", $e->getLine(), "\n";
}

restore_error_handler();

O handler recebe o nível do erro como primeiro argumento, então pode tratar cada nível de um jeito. Este só registra depreciações em log e transforma todo o resto em exceção:

<?php
set_error_handler(function (int $severity, string $message): bool {
    if ($severity === E_DEPRECATED || $severity === E_USER_DEPRECATED) {
        echo "[log] deprecated: $message\n";
        return true; // handled, PHP does nothing more
    }
    throw new ErrorException($message, 0, $severity);
});

trigger_error("oldFunction() is deprecated, use newFunction()", E_USER_DEPRECATED);

try {
    trigger_error("Config value 'timeout' is missing", E_USER_WARNING);
} catch (ErrorException $e) {
    echo "Exception: ", $e->getMessage(), "\n";
}

Erros fatais e erros de sintaxe nunca chegam ao handler, porque o script não consegue continuar depois deles. Para registrá-los, cadastre uma função de shutdown que lê error_get_last().

Ler o último erro com error_get_last

Algumas funções retornam false e informam o motivo só como aviso, por exemplo file_get_contents num arquivo que não existe. error_get_last() retorna esse aviso como array, o que é útil quando você quer mostrar sua própria mensagem:

<?php
$content = @file_get_contents('missing-config.json');

if ($content === false) {
    $error = error_get_last();
    echo "Could not read the file.\n";
    echo "Type: ", $error['type'] === E_WARNING ? 'E_WARNING' : $error['type'], "\n";
    echo "Message: ", $error['message'], "\n";
}

O operador @ na frente da chamada suprime a mensagem daquela expressão. Use com moderação e só quando você verifica o resultado logo em seguida, como aqui; um @ sozinho só esconde bugs.

Erro comum: os erros estão ligados, mas a página continua em branco

Se você adicionou ini_set('display_errors', '1') e ainda vê uma página branca, o erro provavelmente é de sintaxe. O PHP analisa o arquivo inteiro antes de rodar a primeira linha, então um ; ou } faltando para tudo antes de o ini_set rodar. Verifique o arquivo pelo terminal, que sempre imprime a mensagem:

php -l index.php

Errors parsing index.php
PHP Parse error:  syntax error, unexpected token "," in index.php on line 2

O número da linha aponta onde o PHP desistiu, que muitas vezes é a linha depois do erro de verdade. Corrija, rode php -l de novo até aparecer No syntax errors detected e recarregue a página.