error_log()

Registrando Erros PHP com a Função Error Log

Exibir erros na tela com echo ou var_dump() é útil durante o desenvolvimento de um recurso, mas é a ferramenta errada em produção: a saída na tela fica visível para os visitantes, se perde em chamadas AJAX e desaparece no momento em que a requisição termina. A função embutida error_log() resolve isso enviando uma mensagem para algum lugar durável — um arquivo de log, um e-mail ou o logger do sistema operacional — para que você possa revisá-la depois.

Este guia explica o que error_log() faz, percorre cada parâmetro com exemplos executáveis e aborda as armadilhas (novas linhas no final, a diretiva ini error_log, o que não registrar) que atrapalham as pessoas em projetos reais.

O que a função error_log() faz

error_log() grava uma única mensagem em um destino que você escolhe. Ela não aciona o mecanismo de erros do PHP, não altera o código de saída nem interrompe o script — apenas registra texto. O valor de retorno é um bool: true em caso de sucesso, false se a mensagem não pôde ser gravada (por exemplo, o arquivo de log não tem permissão de escrita).

Por ser apenas "adicionar esta string em algum lugar", error_log() é a forma mais simples de deixar rastros em código que executa sem um desenvolvedor assistindo — cron jobs, workers de fila, webhooks e qualquer requisição em produção.

Assinatura da função

error_log(
    string $message,
    int $message_type = 0,
    ?string $destination = null,
    ?string $additional_headers = null
): bool

O padrão: registrar no destino configurado do PHP

A chamada mais comum passa apenas a mensagem e deixa o PHP roteá-la para onde o servidor está configurado para enviar erros (a diretiva ini error_log, ou o logger do SAPI/sistema, se não estiver definida):

<?php

error_log("Payment gateway returned an unexpected status code");

Esse é exatamente o local onde avisos e notificações não capturados já vão, então suas mensagens manuais ficam ao lado das próprias do PHP. Para ver o destino atual em tempo de execução, leia o valor ini:

<?php

echo ini_get('error_log') ?: '(SAPI / system default)';

Registrando em um arquivo específico (tipo 3)

O tipo 3 acrescenta a mensagem a um arquivo que você nomeia em $destination. Este é o recurso principal para logs específicos da aplicação:

<?php

$message = "Error: Unable to connect to the database";
error_log($message, 3, "/var/log/php-errors.log");

Ao contrário do tipo 0, o tipo 3 grava a mensagem literalmente — sem timestamp, sem severidade e, crucialmente, sem nova linha no final. Se você esquecer a nova linha, todas as chamadas ficarão juntas em uma única linha:

<?php

$log = sys_get_temp_dir() . "/app.log";
error_log("first", 3, $log);
error_log("second", 3, $log);
echo file_get_contents($log); // firstsecond

Adicione PHP_EOL você mesmo (e geralmente um timestamp) para que cada entrada seja uma linha legível:

<?php

$log = sys_get_temp_dir() . "/app.log";
$line = date('[Y-m-d H:i:s] ') . "Cache miss for user 42" . PHP_EOL;
error_log($line, 3, $log);

echo file_get_contents($log);
// [2026-06-21 10:00:00] Cache miss for user 42

Todos os tipos de mensagem

O tipo 2 (enviar por socket TCP) existia em versões antigas do PHP e foi removido no PHP 8; não o utilize.

Enviando erros críticos por e-mail (tipo 1)

Para falhas raras e de alta severidade, você pode fazer o PHP enviar um e-mail. Use com moderação — um erro barulhento que dispara uma vez por requisição pode inundar uma caixa de entrada:

<?php

error_log(
    "FATAL: order processor crashed",
    1,
    "[email protected]",
    "From: [email protected]\r\n"
);

Em produção, uma biblioteca de logging que agrupa e limita a taxa de alertas é mais adequada do que enviar e-mail a cada chamada.

Um padrão realista de captura e registro

No código da aplicação, você geralmente registra dentro de um bloco catch, grava contexto suficiente para reproduzir o problema e exibe uma mensagem genérica para o usuário:

<?php

function chargeCustomer(int $cents): bool
{
    if ($cents <= 0) {
        throw new InvalidArgumentException("Amount must be positive, got $cents");
    }
    // ... real charge logic ...
    return true;
}

try {
    chargeCustomer(-5);
} catch (Throwable $e) {
    error_log(sprintf(
        "[%s] %s in %s:%d",
        date('Y-m-d H:i:s'),
        $e->getMessage(),
        $e->getFile(),
        $e->getLine()
    ));
    echo "Sorry, we couldn't process your payment.";
}

A mensagem detalhada vai para o log; o visitante só vê a linha amigável. Essa separação é o objetivo principal do error_log().

Armadilhas comuns

• Sem nova linha com o tipo 3. Adicione PHP_EOL você mesmo ou suas entradas serão concatenadas.
• A diretiva ini error_log define o destino padrão. Quando você omite $message_type/$destination, a mensagem vai para onde ini_get('error_log') aponta. Em uma instalação CLI nova, isso pode ser stderr; em um servidor web, pode ser um arquivo específico.
• O arquivo deve ter permissão de escrita pelo processo PHP. Um retorno false geralmente indica um problema de permissões no diretório ou arquivo.
• display_errors e error_log são independentes. Desativar erros na tela não interrompe o registro em log, e vice-versa — controle-os separadamente.
• Nunca registre segredos. Senhas, chaves de API, números completos de cartão de crédito e tokens de sessão nunca devem chegar a um arquivo de log. Mascare-os antes de chamar error_log().

Funções relacionadas

• set_error_handler() — roteie os próprios avisos e notificações do PHP pelo seu código para poder chamar error_log() de forma consistente.
• set_exception_handler() — capture e registre exceções não capturadas em um único lugar.
• trigger_error() — dispare um erro no nível do usuário que o manipulador de erros (e, portanto, o logging) vai capturar.
• error_reporting() — escolha quais níveis de erro são reportados.
• syslog() — envie mensagens diretamente ao logger do sistema com um nível de severidade.

Conclusão

error_log() é a forma mais simples e durável de registrar o que deu errado em código que nenhum desenvolvedor está observando. Use o tipo 3 com um timestamp e PHP_EOL para arquivos de log da aplicação, recorra ao destino padrão para ficar ao lado dos próprios erros do PHP e reserve o e-mail (tipo 1) para eventos genuinamente críticos. Combine com set_error_handler() e set_exception_handler() para capturar tudo em um único lugar — e nunca grave segredos em um log.

Prática