LogHole

Requisitos

O LogHole tem versoes alinhadas com cada major do Laravel. Escolha a release correspondente a sua stack:

Bases de dados suportadas: MySQL, MariaDB, PostgreSQL, SQLite e SQL Server.

Configuracao

O ficheiro de configuracao publicado fica em config/log-hole.php:

return [
    'database' => [
        'driver' => 'custom',
        'via' => DigitalDevLx\LogHole\Channels\DatabaseChannel::class,
        'level' => env('LOG_LEVEL', 'debug'),
        'table' => 'logs_hole',
    ],

    // Conexao a usar para os logs (null = conexao default)
    'connection' => env('LOG_HOLE_DB_CONNECTION', null),

    // Emails autorizados a aceder ao dashboard (vazio = aberto)
    'authorized_users' => [],

    // Prefixo da rota do dashboard
    'dashboard_route' => 'log-hole',

    // Logs por pagina no dashboard
    'per_page' => 25,

    // Auto-refresh do dashboard de 5 em 5 segundos
    'auto_refresh' => false,

    // TTL (segundos) para a query stats(). 0 desactiva.
    // Util quando o dashboard auto-refreshar contra uma tabela enorme.
    'stats_cache_ttl' => env('LOG_HOLE_STATS_CACHE_TTL', 0),
];

Adicionar o canal de logging

Adicione o canal database ao config/logging.php:

'channels' => [
    // ... outros canais

    'database' => config('log-hole.database'),
],

Opcoes de utilizacao do canal

Opcao A -- definir como canal default no .env:

LOG_CHANNEL=database

Opcao B -- usar dentro de um stack:

'channels' => [
    'stack' => [
        'driver' => 'stack',
        'channels' => ['single', 'database'],
    ],

    'database' => config('log-hole.database'),
],

Opcao C -- usar on-demand:

use Illuminate\Support\Facades\Log;

Log::channel('database')->info('Esta vai para a base de dados');

Conexao de base de dados separada

Para guardar logs noutra base de dados, defina LOG_HOLE_DB_CONNECTION. A conexao tem de existir em config/database.php e a migration deve ser executada nessa conexao.

LOG_HOLE_DB_CONNECTION=mysql_logs

Cache de stats no dashboard

Em tabelas com milhoes de linhas, a query de COUNT(*) por nivel que alimenta a barra de stats e cara. Com auto-refresh ligado, corre de 5 em 5 segundos por visitante. Ative cache positivo via TTL:

LOG_HOLE_STATS_CACHE_TTL=5

O driver usa o cache store default do Laravel sob a chave log-hole:stats:{connection}:{table}.

Atributo #[Loggable]

O LogHole expoe o atributo #[Loggable] para logging declarativo em metodos de controllers e classes inteiras. Quando o middleware LogHoleMiddleware esta activo, as accoes anotadas sao registadas automaticamente apos o request ser processado.

Configurar middleware (Laravel 11+)

use DigitalDevLx\LogHole\Middlewares\LogHoleMiddleware;

return Application::configure(basePath: dirname(__DIR__))
    // ...
    ->withMiddleware(function (Middleware $middleware) {
        $middleware->append(LogHoleMiddleware::class);
    })
    ->create();

Setups antigos (Laravel 10.x com app/Http/Kernel.php) sao suportados pelo LogHole 2.x. As versoes 3 e 4 esperam o bootstrap de middleware do Laravel 11+.

Atributo a nivel de metodo

use DigitalDevLx\LogHole\Attributes\Loggable;

class OrderController extends Controller
{
    #[Loggable(message: 'Encomenda criada', level: 'info')]
    public function store(Request $request)
    {
        // ... logica
    }

    #[Loggable(message: 'Encomenda eliminada', level: 'warning')]
    public function destroy(Order $order)
    {
        // ... logica
    }
}

Atributo a nivel de classe

Aplicado a classe, todas as accoes do controller sao registadas automaticamente. Atributos de metodo tem prioridade sobre os de classe.

use DigitalDevLx\LogHole\Attributes\Loggable;

#[Loggable(level: 'info')]
class UserController extends Controller
{
    public function index() { /* registado automaticamente */ }
    public function show(User $user) { /* registado automaticamente */ }
}

Parametros do atributo

Usar o LogLevel enum

use DigitalDevLx\LogHole\Attributes\Loggable;
use DigitalDevLx\LogHole\Enums\LogLevel;

#[Loggable(
    message: 'Acao critica executada',
    level: LogLevel::Critical,
    includeRequest: true,
)]
public function dangerousAction()
{
    // ...
}

Artisan -- log-hole:tail

O comando log-hole:tail permite consultar e purgar logs directamente no terminal, com output tabular e contexto em JSON formatado.

# Ultimos 10 logs (default)
php artisan log-hole:tail

# Filtrar por nivel
php artisan log-hole:tail --error
php artisan log-hole:tail --critical
php artisan log-hole:tail --warning

# Filtrar por intervalo de datas
php artisan log-hole:tail --error --from=2024-10-01 --to=2024-10-31

# Limitar resultados
php artisan log-hole:tail --critical --take=5

# Purgar todos os logs (com confirmacao)
php artisan log-hole:tail --purge

Opcoes disponiveis

Sem opcao de nivel, todos os niveis sao retornados. O contexto e mostrado em JSON pretty-printed para legibilidade.

Tabela de logs

A migration cria a tabela logs_hole (configuravel via config('log-hole.database.table')) com a seguinte estrutura:

Indexes: logged_at e composto (level, logged_at) -- que tambem cobre filtros so-por-nivel via leftmost-prefix.

Guia de upgrade

v3.x → v4.0

v4 e uma release Laravel 13 sem breaks de API publica. A camada de drivers foi reformulada internamente para corrigir bugs de escape de wildcards LIKE em PostgreSQL e SQL Server, e para unificar a semantica de pesquisa entre MySQL/MariaDB. Se so usou a facade Log, o dashboard, o comando log-hole:tail ou #[Loggable], o upgrade e directo:

composer require digitaldev-lx/log-hole:^4.0

Se implementou um driver custom contra LogDriverInterface, note que purge() aceita agora um terceiro argumento opcional int $chunkSize = 0. Callers existentes continuam a funcionar -- o novo argumento tem default backwards-compatible.

v1.x → v2.0

1. Estrutura do config mudou -- republique o ficheiro:
   Republish config

   bash Copiar Copiado!

   php artisan vendor:publish --tag="log-hole-config" --force

2. Tag de publish renomeada -- de --tag=logs-config para --tag=log-hole-config (convencao Spatie).
3. Atributo #[Loggable] -- a propriedade level e agora um enum LogLevel (strings ainda funcionam por backwards-compat). A propriedade publica $level foi removida em favor de $logLevel (readonly enum).
4. Views e routes mudaram de localizacao -- views passaram de src/resources/views/ para resources/views/; routes passaram de src/routes/ para routes/. Se publicou views, republique-as.
5. Indexes da migration -- volte a correr migrations para adicionar os novos indexes de performance:
   Re-migrate

   bash Copiar Copiado!

   php artisan migrate

Testes

O pacote inclui 175 testes Pest, analise estatica PHPStan level 6 e formatacao PSR-12 com Laravel Pint. Existe ainda uma suite de integracao separada que corre contra Postgres 16 e MySQL 8.4 reais em CI.

# Suite default (Pest, SQLite in-memory)
composer run test

# Testes com cobertura
composer run test-coverage

# Analise estatica (PHPStan level 6)
composer run analyse

# Formatacao (Laravel Pint, PSR-12)
composer run format

# Analyse + format combinado
composer run check

Para correr a suite de integracao contra Postgres ou MySQL real (skip por defeito), defina LOG_HOLE_INTEGRATION_DB:

LOG_HOLE_INTEGRATION_DB=pgsql DB_HOST=127.0.0.1 DB_PORT=5432 \
DB_DATABASE=log_hole_test DB_USERNAME=postgres DB_PASSWORD=postgres \
vendor/bin/pest --testsuite=integration