Logging em aplicações PHP: melhores práticas na prática

Treinador Online de Python para Iniciantes

Aprenda Python facilmente sem sobrecarga teórica. Resolva tarefas práticas com verificação automática e escreva código diretamente no navegador.

Start Course

Logging em aplicações PHP: melhores práticas na prática

Logging não é apenas registrar erros em um arquivo. É uma ferramenta estratégica de monitoramento, depuração e auditoria do funcionamento da aplicação. Neste artigo, vamos analisar como organizar o logging em PHP na prática, usando abordagens e bibliotecas modernas. Você aprenderá como evitar erros típicos e tornar os logs realmente úteis.

1. Escolha da biblioteca e padrão PSR-3

Na comunidade PHP moderna, o padrão de facto é a interface PSR-3 (Logger Interface). Ela define um conjunto unificado de métodos para logging, permitindo trocar facilmente a biblioteca de logging sem reescrever o código da aplicação.

A implementação mais popular do PSR-3 é a biblioteca Monolog. Ela é flexível, performática e possui diversos "handlers" para enviar logs para arquivos, bancos de dados, Slack, Telegram, Email e serviços em nuvem.

Instalação do Monolog via Composer:

composer require monolog/monolog

Exemplo básico de uso:

<?phprequire 'vendor/autoload.php';

use Monolog\\Logger;use Monolog\\Handler\\StreamHandler;

// Criamos um canal (channel) de logs — geralmente pelo nome da aplicação ou módulo$log = new Logger('my_app');// Adicionamos um handler: escrevemos logs de nível WARNING e superiores em um arquivo$log->pushHandler(new StreamHandler(__DIR__ . '/logs/app.log', Logger::WARNING));

// Agora podemos registrar logs$log->warning('Usuário {username} tentou fazer login com senha incorreta', ['username' => 'ivan']);$log->error('Não foi possível conectar ao banco de dados: {error}', ['error' => $e->getMessage()]);?>

Por que isso é importante? Usar o PSR-3 torna seu código independente de uma biblioteca específica. Se amanhã você quiser migrar do Monolog para outra implementação (por exemplo, Log4php), precisará alterar apenas a inicialização do logger, e não todos os lugares onde $log->error() é chamado.

2. Níveis de logging: quando usar cada um

O PSR-3 define 8 níveis de logging (da prioridade mais baixa para a mais alta): DEBUG, INFO, NOTICE, WARNING, ERROR, CRITICAL, ALERT, EMERGENCY. O uso correto dos níveis é a base para logs legíveis e úteis.

DEBUG — informações detalhadas de depuração, necessárias apenas para o desenvolvedor (valores de variáveis, rastreamento de chamadas). Ative apenas no ambiente de desenvolvimento.
INFO — eventos importantes do funcionamento da aplicação: usuário registrado, pedido criado, tarefa cron concluída.
NOTICE — eventos normais, mas significativos (por exemplo, uso de API obsoleta).
WARNING — problemas potenciais que não interromperam a execução do script (tentativa de login mal-sucedida, consulta lenta ao banco de dados).
ERROR — erros que exigem intervenção: exceções, falhas em serviços externos.
CRITICAL — falhas críticas: perda de conexão com o banco de dados, falta de memória.
ALERT — ação imediata do administrador necessária (site indisponível).
EMERGENCY — todo o sistema está inoperante.

Dica prática: Configure diferentes handlers para diferentes níveis. Por exemplo, WARNING e superiores escreva em um arquivo, e ERROR e superiores envie também para Telegram/Slack.

// Exemplo: dois handlers para o mesmo logger$log->pushHandler(new StreamHandler(__DIR__ . '/logs/all.log', Logger::DEBUG));$log->pushHandler(new StreamHandler(__DIR__ . '/logs/errors.log', Logger::ERROR));// Para erros críticos — envio para o Telegram$log->pushHandler(new TelegramBotHandler('TOKEN', 'CHAT_ID', Logger::CRITICAL));