Registro de logs em aplicações PHP: melhores práticas e ferramentas

Registro em Aplicações PHP: Melhores Práticas

Registro (logging) não é apenas gravar erros em um arquivo. É um processo sistemático de coleta, armazenamento e análise de informações sobre a operação de uma aplicação. No desenvolvimento PHP, um registro bem configurado ajuda a encontrar bugs rapidamente, rastrear anomalias no comportamento do usuário e garantir auditoria de segurança. Neste artigo, abordaremos as melhores práticas de registro em PHP, desde padrões até ferramentas avançadas.

1. Por que o registro é necessário e princípios básicos

O registro resolve várias tarefas principais:

• Depuração — captura do estado da aplicação no momento do erro.
• Monitoramento — rastreamento de desempenho e carga.
• Segurança — registro de ações suspeitas (tentativas de invasão, acesso não autorizado).
• Auditoria — documentação de operações críticas de negócios.

Princípios básicos de um bom registro:

• Não minta — os logs devem refletir o estado real do sistema.
• Estruturação — use um formato único (JSON, key=value).
• Níveis de importância — separe debug, info, warning, error, critical.
• Sem segredos — nunca escreva senhas, tokens ou dados pessoais.

2. Padrão PSR-3 e a Interface LoggerInterface

O PHP-FIG recomenda usar PSR-3 — uma interface padrão para bibliotecas de registro. Ela define 8 níveis (de debug a emergency) e um contrato único.

Exemplo de implementação usando PSR-3:

<?phpuse Psr\\Log\\AbstractLogger;

class SimpleLogger extends AbstractLogger{    public function log($level, $message, array $context = [])    {        $logEntry = sprintf(            '[%s] %s: %s %s',            date('Y-m-d H:i:s'),            strtoupper($level),            $message,            json_encode($context)        );        file_put_contents('/var/log/app.log', $logEntry . PHP_EOL, FILE_APPEND);    }}

$logger = new SimpleLogger();$logger->info('Usuário registrado', ['user_id' => 42]);?>

Usar PSR-3 permite substituir facilmente a biblioteca de logger (por exemplo, de Monolog para uma implementação própria) sem alterar o código da aplicação.

3. Monolog — Ferramenta Poderosa para Registro

Monolog é a biblioteca de registro mais popular para PHP (instalação via Composer: composer require monolog/monolog). Ela suporta vários handlers e formatadores.

Configuração Básica do Monolog

<?phpuse Monolog\\Logger;use Monolog\\Handler\\StreamHandler;use Monolog\\Handler\\FirePHPHandler;use Monolog\\Formatter\\LineFormatter;

$logger = new Logger('my_app');

// Handler para arquivo$fileHandler = new StreamHandler(__DIR__ . '/logs/app.log', Logger::WARNING);$fileHandler->setFormatter(new LineFormatter("[%datetime%] %level_name%: %message% %context%"));$logger->pushHandler($fileHandler);

// Handler para navegador (FirePHP)$logger->pushHandler(new FirePHPHandler());

// Uso$logger->warning('Permissões insuficientes', ['user' => 'guest']);$logger->error('Erro de conexão com o BD', ['db_host' => 'localhost']);?>

Recursos Avançados do Monolog

• FingersCrossedHandler — armazena logs em buffer e grava apenas ao atingir um determinado nível (economiza espaço).
• GroupHandler — envia logs para vários canais simultaneamente (arquivo + Email + Slack).
• Processors — adicionam contexto (endereço IP, ID de sessão, tempo de execução).

Exemplo com processor para adicionar IP: