Psr/Log para PHP: guia completo com exemplos práticos

O logging é um dos aspectos mais importantes no desenvolvimento de qualquer aplicação séria. Sem ele, é impossível depurar erros em produção, rastrear o comportamento dos usuários ou analisar o desempenho do sistema. No entanto, se o projeto utiliza várias bibliotecas, cada uma escrevendo logs de forma diferente, o desenvolvedor enfrenta um caos: níveis diferentes, formatos diferentes, formas de saída diferentes. Foi exatamente para resolver esse problema que o padrão PSR-3 (Logger Interface) foi criado.

Psr/Log não é uma biblioteca de logging em si, mas uma interface padrão (um conjunto de contratos) que define como um logger universal deve ser em PHP. Ele fornece oito métodos para registrar mensagens de diferentes níveis de importância (emergency, alert, critical, error, warning, notice, info, debug), além de um método universal log(). Qualquer biblioteca que implemente o PSR-3 pode ser facilmente integrada em qualquer projeto que espere essa interface. Isso permite que o desenvolvedor troque a implementação do logger (por exemplo, de Monolog para Analog) sem alterar o código da aplicação.

Neste artigo, vamos detalhar a biblioteca psr/log, desde a instalação até exemplos práticos avançados. Você aprenderá a usar cada método corretamente, como formatar mensagens com placeholders e como evitar erros comuns. O conteúdo é útil tanto para iniciantes em PHP quanto para desenvolvedores experientes que desejam organizar seus conhecimentos.

Instalação

A biblioteca psr/log é instalada via Composer, o gerenciador de dependências padrão do PHP. Execute o seguinte comando no terminal:

composer require psr/log

Após a instalação, o diretório vendor/psr/log será criado no seu projeto. Se você usa um framework (Laravel, Symfony), o PSR-3 provavelmente já está incluído. Para carregar o autoloader no seu script PHP, adicione a linha:

require __DIR__ . '/vendor/autoload.php';

Importante: psr/log é apenas a interface. Para realmente escrever logs, você precisará de uma implementação, como monolog/monolog. Instalação do Monolog:

composer require monolog/monolog

Primeiros passos

Vamos criar um exemplo simples de logging usando Monolog (a implementação PSR-3 mais popular).

<?php
require 'vendor/autoload.php';

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

// Cria um logger com o nome 'meu_logger'
$log = new Logger('meu_logger');

// Adiciona um handler: escreve todas as mensagens de nível DEBUG ou superior no arquivo app.log
$log->pushHandler(new StreamHandler(__DIR__ . '/app.log', Logger::DEBUG));

// Registra algumas mensagens
$log->info('Aplicação iniciada');
$log->warning('Não foi possível carregar o arquivo de configuração, usando valores padrão');
$log->error('Erro crítico: banco de dados indisponível');

echo "Logs registrados. Verifique o arquivo app.log";

Após executar este script, o arquivo app.log conterá algo como:

[2025-04-10T15:30:45.123456+00:00] meu_logger.INFO: Aplicação iniciada [] []
[2025-04-10T15:30:45.123789+00:00] meu_logger.WARNING: Não foi possível carregar o arquivo de configuração, usando valores padrão [] []
[2025-04-10T15:30:45.124012+00:00] meu_logger.ERROR: Erro crítico: banco de dados indisponível [] []

Este é um exemplo funcional mínimo. Agora vamos detalhar cada método da interface.

Métodos principais da interface Psr\Log\LoggerInterface

A interface Psr\Log\LoggerInterface define 9 métodos. Os primeiros 8 são métodos para níveis específicos de logging, e o nono é o método universal log().