Monolog PHP: métodos, exemplos, instalação

O que é Monolog e para que serve?

\n\n

Monolog é uma biblioteca padrão para logging em PHP. Ela fornece um conjunto de ferramentas flexível e poderoso para registrar logs em vários canais (arquivos, bancos de dados, e-mail, syslog, serviços externos, etc.). Monolog é o padrão de facto para aplicações PHP, especialmente no ecossistema Symfony, Laravel e outros frameworks modernos.

\n\n

Para que serve esta biblioteca? Em qualquer aplicação, é necessário monitorar eventos: erros, avisos, mensagens informativas, informações de depuração. Monolog permite:

Centralizar o logging — escrever logs em um formato único e de qualquer lugar da aplicação.
Configurar canais de forma flexível — enviar erros críticos para o Telegram/Slack e mensagens informativas para um arquivo.
Formatar mensagens — adicionar data, nível, contexto, stack trace.
Filtrar logs — processar apenas mensagens de um determinado nível.
Integrar-se com frameworks — em Symfony, Laravel, Yii2, o Monolog é utilizado.

\n\n

Instalação

O Monolog é instalado via Composer — o gerenciador de pacotes padrão para PHP.

composer require monolog/monolog

Se você estiver usando PHP 8.0+, é recomendável instalar a versão estável mais recente. Após a instalação, a pasta vendor e o arquivo composer.json com a dependência serão criados no projeto.

\n\n

Início rápido

O exemplo mais simples — registrar um log em um arquivo:

<?php\nrequire 'vendor/autoload.php';\n\nuse Monolog\\Logger;\nuse Monolog\\Handler\\StreamHandler;\n\n// Criamos um logger com o nome do canal 'my_app'\n$log = new Logger('my_app');\n// Adicionamos um handler — gravação em arquivo\n$log->pushHandler(new StreamHandler('app.log', Logger::WARNING));\n\n// Agora podemos registrar logs\n$log->warning('Isto é um aviso');\n$log->error('Isto é um erro');\n\necho "Logs gravados em app.log";\n?>

Após a execução do script, no arquivo app.log aparecerá algo como:

[2025-04-09T10:30:00.123456+00:00] my_app.WARNING: Isto é um aviso [] []\n[2025-04-09T10:30:00.123789+00:00] my_app.ERROR: Isto é um erro [] []

\n\n

Principais métodos e funções

Vamos analisar os principais métodos do Monolog. Todos eles fazem parte da classe Monolog\\Logger ou de classes relacionadas.

\n\n

1. `pushHandler(HandlerInterface $handler)`

O que faz: Adiciona um handler à pilha. O logger pode ter vários handlers, e cada um receberá todas as mensagens (se a filtragem não estiver configurada).

Parâmetros:

$handler — objeto que implementa Monolog\\Handler\\HandlerInterface (por exemplo, StreamHandler, FirePHPHandler, SlackHandler).

Exemplo:

$log = new Logger('app');\n$log->pushHandler(new StreamHandler('debug.log', Logger::DEBUG));\n$log->pushHandler(new StreamHandler('errors.log', Logger::ERROR));\n// Agora, mensagens de nível ERROR e superiores serão registradas em ambos os arquivos

\n\n

2. `addRecord(int $level, string $message, array $context = [])`

O que faz: Método básico para registrar um log. Normalmente não é chamado diretamente; em vez disso, são usados métodos wrapper (debug(), info(), etc.).

Parâmetros:

$level — nível de logging (constantes: Logger::DEBUG, Logger::INFO, Logger::WARNING, etc.).
$message — texto da mensagem.
$context — array de dados adicionais (por exemplo, ID do usuário, endereço IP).

Exemplo: