Logging em aplicações PHP: melhores práticas para iniciantes

Logging em aplicações PHP: melhores práticas para iniciantes

Logging é o processo de registrar informações sobre a operação de uma aplicação em arquivos especiais (logs). Para desenvolvedores PHP iniciantes, saber configurar corretamente o logging é tão importante quanto conhecer a sintaxe da linguagem. Os logs ajudam a:

\n
• Capturar erros que não são visíveis na tela (por exemplo, em ambiente de produção).
\n
• Monitorar o comportamento dos usuários e a operação do sistema.
\n
• Realizar auditoria de segurança.
\n
• Acelerar a depuração de bugs complexos.
\n

Neste artigo, abordaremos as melhores práticas de logging em PHP: desde a função nativa error_log() até o uso de bibliotecas profissionais como Monolog. Você aprenderá como não poluir o código, escolher corretamente os níveis de logging e evitar erros típicos de iniciantes.

1. Fundamentos: logging nativo em PHP

A maneira mais simples de registrar algo em um log é usar a função error_log(). Ela pode enviar mensagens para o log do sistema do servidor, para um arquivo específico ou para um e-mail.

Exemplo de logging básico

<?php\n// Gravação no log do sistema (syslog)\nerror_log('Esta é uma mensagem de erro');\n\n// Gravação em um arquivo específico\nerror_log('Erro de conexão com o BD', 3, '/var/log/my_app_errors.log');\n?>

Vantagens: não requer instalação de bibliotecas, funciona "pronto para uso".

Desvantagens:

\n
• Sem flexibilidade (não é possível alterar facilmente o formato de saída).
\n
• Difícil filtrar por nível de importância.
\n
• Incômodo ao trabalhar com vários canais (arquivo, banco de dados, Slack).
\n

Para scripts simples e aprendizado, isso é suficiente, mas para projetos sérios, é melhor usar soluções mais avançadas.

2. Níveis de logging: quando e o que registrar

Para que os logs sejam úteis e não "ruído", é importante classificar as mensagens por nível de gravidade. O padrão PSR-3 (que abordaremos a seguir) oferece 8 níveis:

\n
• DEBUG — informações de depuração (valores de variáveis, tempo de execução). Usado apenas na fase de desenvolvimento.
\n
• INFO — mensagens informativas (usuário registrado, requisição processada).
\n
• NOTICE — eventos normais, mas importantes (uso de API obsoleta).
\n
• WARNING — avisos (algo deu errado, mas a aplicação continua funcionando, por exemplo, formato de entrada inválido).
\n
• ERROR — erros que exigem intervenção (não foi possível salvar o arquivo).
\n
• CRITICAL — erros críticos (componente principal do sistema indisponível).
\n
• ALERT — requer ação imediata (invasão, falha no banco de dados).
\n
• EMERGENCY — sistema inoperante.
\n

Exemplo de uso de níveis (sem bibliotecas)

<?php\nfunction logMessage($level, $message) {\n    $logFile = __DIR__ . '/app.log';\n    $timestamp = date('Y-m-d H:i:s');\n    $formatted = "[{$timestamp}] [{$level}] {$message}" . PHP_EOL;\n    file_put_contents($logFile, $formatted, FILE_APPEND);\n}\n\nlogMessage('INFO', 'Usuário fez login no sistema');\nlogMessage('ERROR', 'Falha ao conectar ao banco de dados');\n?>

Dica: Nunca registre senhas, tokens ou consultas SQL completas com dados de usuários nos logs — isso é uma ameaça à segurança.

3. PSR-3 e Monolog: abordagem profissional

PSR-3 é uma recomendação do PHP-FIG que descreve uma interface unificada para bibliotecas de logging. A implementação mais popular do PSR-3 é o Monolog. Ela é usada em Laravel, Symfony e muitos outros frameworks.

Instalação do Monolog via Composer

composer require monolog/monolog

Exemplo simples com Monolog

<?php\nrequire 'v