Erro PHP

Encontrar erros é uma parte normal da programação em PHP. Quanto mais rápido você conseguir ler um erro e entender qual é o nível, por que o PHP o gerou e como responder, mais rápido você entrega um código funcional. Esta página explica os níveis de erro do PHP (as constantes E_*), a diferença entre erros e exceções no PHP moderno, e um fluxo de trabalho prático para relatórios, registro e tratamento de erros.

Níveis de Erro do PHP

Quando o PHP detecta um problema, ele o levanta em um nível específico, identificado por uma constante E_*. O nível indica a gravidade do problema e se o script continua em execução. Você combina essas constantes com error_reporting() e a diretiva error_reporting do php.ini para decidir quais níveis são exibidos ou registrados.

Estas são constantes de máscara de bits, portanto, você as combina com o operador OR bit a bit (|) e exclui níveis com & mais ~:

<?php
// Report everything except notices and deprecations
error_reporting(E_ALL & ~E_NOTICE & ~E_DEPRECATED);

Importante: Desde o PHP 8.0, muitos antigos warnings e notices foram promovidos a exceções Error lançadas (por exemplo, ler uma chave de array indefinida agora gera um aviso, enquanto chamar um método indefinido lança um Error). Saber se um problema é um erro gerado ou uma exceção lançada determina como você o captura — veja abaixo.

Erros vs. Exceções

O PHP possui dois mecanismos relacionados, mas distintos:

• Erros tradicionais são gerados pelo motor e roteados por error_reporting, display_errors e um manipulador opcional definido com set_error_handler(). Eles não são objetos que você pode capturar com catch (a menos que seu manipulador os converta).
• Exceções são objetos que você throw e catch com blocos try/catch. Desde o PHP 7, problemas fatais do motor também são lançados como objetos Error (como TypeError ou DivisionByZeroError), e tanto Exception quanto Error implementam a interface Throwable — portanto, catch (\Throwable $e) captura qualquer coisa que possa ser capturada.

<?php
try {
    // intdiv() throws a DivisionByZeroError on division by zero
    echo intdiv(10, 0);
} catch (\Throwable $e) {
    echo get_class($e) . ": " . $e->getMessage();
}
// Output: DivisionByZeroError: Division by zero

Causas Comuns de Erros PHP

A maioria dos erros se origina de um pequeno conjunto de causas:

• Erros de sintaxe — um ponto e vírgula ausente ou um colchete sem par (E_PARSE).
• Símbolos indefinidos — usar uma variável, constante, função ou chave de array que não existe.
• Incompatibilidade de tipos — passar o tipo errado para um parâmetro tipado (lança TypeError).
• Recursos obsoletos — funções ou sintaxe programadas para remoção (E_DEPRECATED).
• Limites de recursos — esgotar memory_limit ou atingir max_execution_time.
• Falhas externas — um arquivo ausente, ou uma conexão com banco de dados/API que recusa ou expira.
• Exceções não capturadas — um throw sem nenhum catch correspondente, o que se torna um erro fatal.

<?php
// Reading an undefined variable raises an E_WARNING and yields null
echo $undefined_variable ?? "fallback";
// Output: fallback

O operador null-coalescing (??) acima é a forma idiomática de ler um valor que pode ser indefinido sem acionar um aviso.

Configurando o Relatório de Erros

Controle quais níveis aparecem e para onde vão. Em desenvolvimento, exiba tudo; em produção, oculte os erros dos usuários, mas registre-os.

<?php
// Development: show all errors on screen
error_reporting(E_ALL);
ini_set('display_errors', '1');

// Production: hide from users, write to the error log instead
// error_reporting(E_ALL);
// ini_set('display_errors', '0');
// ini_set('log_errors', '1');

As configurações equivalentes no php.ini são error_reporting, display_errors, log_errors e error_log. Para controle programático, consulte error_reporting() e, para inspecionar o erro mais recente, use error_get_last().

Tratamento de Erros no Código

Há três ferramentas complementares:

1. Capture exceções com try/catch para que uma falha recuperável não cause a interrupção do script:

<?php
function safeDivide(int $a, int $b): float
{
    if ($b === 0) {
        throw new InvalidArgumentException("Cannot divide by zero");
    }
    return $a / $b;
}

try {
    echo safeDivide(10, 0);
} catch (InvalidArgumentException $e) {
    echo "Handled: " . $e->getMessage();
}
// Output: Handled: Cannot divide by zero

2. Instale um manipulador de erros personalizado com set_error_handler() para converter erros tradicionais em exceções ou para registrá-los no seu próprio formato:

<?php
set_error_handler(function (int $level, string $message, string $file, int $line) {
    // Turn a traditional warning/notice into an ErrorException so it can be caught
    throw new ErrorException($message, 0, $level, $file, $line);
});

try {
    // Reading a missing file raises an E_WARNING, now converted to an exception
    $contents = file_get_contents('/no/such/file.txt');
} catch (\Throwable $e) {
    echo "Caught: " . $e->getMessage();
}
// Output: Caught: file_get_contents(/no/such/file.txt): Failed to open stream: No such file or directory

3. Dispare seus próprios erros com trigger_error() para sinalizar problemas no nível da aplicação pelo mesmo pipeline dos erros do motor.

Boas Práticas

• Defina display_errors como 0 em produção — rastreamentos de pilha expostos são um risco de segurança. Use log_errors e um error_log configurado.
• Desenvolva com error_reporting(E_ALL) para que avisos e recursos obsoletos apareçam cedo.
• Prefira catch (\Throwable $e) no nível superior para capturar tanto Exception quanto Error.
• Nunca silencie problemas com o operador @; corrija a causa ou trate-a explicitamente.
• Centralize o registro com error_log() para que todas as falhas sejam registradas em um único lugar.

Conclusão

Ler um erro PHP começa com seu nível e verificar se é um erro gerado ou uma exceção lançada. Com error_reporting() ajustado por ambiente, um manipulador personalizado que encaminha erros para o sistema de exceções e try/catch ao redor do código que pode falhar, você diagnostica problemas rapidamente e mantém a produção resiliente. Continue com PHP Exceptions e error_reporting() para se aprofundar.

Prática