Laravel Auditing: Como Rastrear Mudanças em Models de Forma Automática
Posted inLaravel

Laravel Auditing: Como Rastrear Mudanças em Models de Forma Automática

Posted inLaravel

Se você desenvolve aplicações com Laravel e precisa manter um histórico das alterações feitas em determinados registros, a auditoria automática de modelos é uma solução indispensável. Neste post, vamos explorar como implementar o Laravel Auditing, um pacote amplamente utilizado para registrar mudanças em modelos de forma prática e eficiente.

O que é auditoria de dados?

Auditoria de dados é o processo de monitoramento, registro e análise de alterações em informações dentro de um sistema. Em aplicações web, esse recurso é fundamental para:

  • Aumentar a transparência das ações dos usuários;
  • Garantir rastreabilidade de mudanças;
  • Atender a requisitos legais e de conformidade;
  • Facilitar a identificação de erros ou fraudes.

Por que usar Laravel Auditing?

O Laravel Auditing é um pacote que simplifica a auditoria de dados. Ele permite registrar automaticamente eventos como criação, atualização e exclusão de registros, armazenando as alterações no banco de dados com informações detalhadas sobre:

  • O que foi alterado;
  • Quando foi alterado;
  • Quem realizou a ação (se o usuário estiver autenticado).

Instalação do Laravel Auditing

Para começar, instale o pacote via Composer:

composer require owen-it/laravel-auditing

Depois, publique as configurações:

php artisan vendor:publish --provider="OwenIt\Auditing\AuditingServiceProvider"

Em seguida, rode as migrações para criar a tabela audits:

php artisan migrate

Essa tabela será responsável por armazenar todos os registros de auditoria do sistema.

Habilitando a auditoria em modelos

Para que um modelo seja auditável, basta implementar a interface Auditable e utilizar o trait \OwenIt\Auditing\Auditable:

use OwenIt\Auditing\Contracts\Auditable as AuditableContract;
use OwenIt\Auditing\Auditable;

class Post extends Model implements AuditableContract
{
    use Auditable;
}

A partir desse momento, qualquer criação, atualização ou exclusão de um registro do modelo Post será registrada automaticamente na tabela audits.

Personalizando os campos auditados

Por padrão, o pacote audita todas as alterações nos atributos do modelo. Porém, você pode personalizar quais campos serão auditados usando o método getAuditInclude():

public function getAuditInclude(): array
{
    return ['title', 'content'];
}

Ou, se quiser excluir campos da auditoria:

public function getAuditExclude(): array
{
    return ['updated_at'];
}

Visualizando os dados de auditoria

Você pode acessar os registros de auditoria diretamente pela relação audits():

$post = Post::find(1);
foreach ($post->audits as $audit) {
    echo "Alterado por: " . $audit->user->name . "\n";
    echo "Modificações: " . json_encode($audit->getModified()) . "\n";
}

Como Registrar o Usuário Responsável nas Auditorias com Laravel Auditing

Para garantir que cada alteração em seus modelos seja devidamente atribuída a um usuário autenticado, o Laravel Auditing utiliza automaticamente o método auth()->user() durante o processo de auditoria.

Certifique-se de que o middleware auth esteja aplicado nas rotas ou controladores relevantes e que o sistema de autenticação do Laravel esteja corretamente configurado. Assim, toda ação realizada por um usuário autenticado será registrada no campo user_id da tabela de auditorias, facilitando o rastreio de responsabilidades.

Essa funcionalidade é essencial para aplicações que exigem transparência, rastreabilidade e controle de acesso, como sistemas administrativos, ERPs e plataformas com múltiplos níveis de permissão.

Como Personalizar o Laravel Auditing para Atender Regras de Negócio Específicas

O Laravel Auditing é uma ferramenta poderosa para registrar automaticamente alterações em modelos, garantindo rastreabilidade e segurança em aplicações web. No entanto, muitas aplicações exigem personalizações específicas, como registrar apenas determinados tipos de ações, ignorar mudanças em certos campos ou auditar apenas em cenários definidos pela lógica de negócio. Neste post, você aprenderá como personalizar o Laravel Auditing para se adequar perfeitamente às necessidades do seu projeto.

Por que personalizar o Laravel Auditing?

Em projetos reais, nem sempre é necessário ou desejável registrar todas as alterações feitas em modelos. A personalização da auditoria permite:

  • Melhorar a performance, evitando registros desnecessários;
  • Manter o banco de dados enxuto;
  • Focar em dados críticos para o negócio;
  • Atender requisitos específicos de conformidade, auditoria interna ou LGPD.

Pré-requisitos

Antes de continuar, é importante que você já tenha o Laravel Auditing instalado e funcionando. Se ainda não fez isso, veja o guia completo aqui.

Auditando Apenas os Campos Importantes: Personalize o Que Registrar no Laravel Auditing

O pacote Laravel Auditing é amplamente utilizado para rastrear alterações em modelos de forma automática e detalhada. Contudo, em muitos projetos, nem todos os campos precisam ser auditados — registrar mudanças em todos os atributos pode causar excesso de informações, ocupar espaço no banco de dados e até comprometer a performance.

Por que auditar apenas campos importantes?

Antes de entrar na parte técnica, é importante entender os benefícios dessa prática:

  • 🔒 Foco na segurança e conformidade: registre apenas os dados críticos, como status, valores financeiros ou campos de controle.
  • ⚙️ Desempenho otimizado: menos registros significa menos consumo de armazenamento e processamento.
  • 📄 Registros mais legíveis: facilita a auditoria manual e análise por equipes de compliance ou administração.
  • 📊 Relatórios mais eficientes: ao evitar ruído nos logs, os relatórios se tornam mais precisos e úteis.

Métodos para controlar os campos auditados

O Laravel Auditing permite duas formas principais de personalização: incluir campos específicos ou excluir campos irrelevantes.

getAuditInclude(): incluí apenas campos desejados

Use este método no seu model para listar somente os atributos que devem ser auditados:

use OwenIt\Auditing\Contracts\Auditable;

class Pedido extends Model implements Auditable
{
    use \OwenIt\Auditing\Auditable;

    public function getAuditInclude(): array
    {
        return ['status', 'valor_total', 'data_pagamento'];
    }
}

Neste exemplo, o Laravel Auditing só registrará alterações nos campos status, valor_total e data_pagamento.

getAuditExclude(): exclui campos desnecessários

Alternativamente, você pode definir quais campos não devem ser auditados:

public function getAuditExclude(): array
{
    return ['updated_at', 'observacoes'];
}

Essa opção é útil quando você quer manter a maioria dos campos auditáveis, exceto alguns específicos.

Casos de uso práticos

Auditoria de pedidos

public function getAuditInclude(): array
{
    return ['status', 'valor_total'];
}

Ideal para registrar apenas quando o status de um pedido muda ou quando o valor total é alterado, desconsiderando alterações em campos como descricao, comentarios ou atualizado_por.

Controle de acesso de usuários

public function getAuditInclude(): array
{
    return ['role', 'status'];
}

Nesse cenário, apenas alterações nas permissões (role) ou na ativação/desativação de contas serão auditadas.

Ignorando campos de controle automático

public function getAuditExclude(): array
{
    return ['updated_at', 'last_login', 'token'];
}

Esses campos geralmente são atualizados com frequência ou por processos automatizados, e não precisam ser auditados em sistemas que priorizam performance.

Dica extra: combine com  shouldAudit()

Você pode ir além e condicionar a auditoria ao tipo de usuário, rota ou situação:

public function shouldAudit(): bool
{
    return auth()->check() && auth()->user()->isAdmin();
}

Com isso, apenas alterações feitas por administradores, e nos campos selecionados, serão registradas.

Exibindo auditorias de forma mais clara

Mesmo auditando poucos campos, os dados podem ficar difíceis de interpretar. Para isso, é possível personalizar a saída com o método transformAudit():

public function transformAudit(array $data): array
{
    $data['modificado_por'] = auth()->user()->name ?? 'Sistema';
    return $data;
}

Ao auditar apenas os campos importantes, você torna sua aplicação mais eficiente, organizada e alinhada às boas práticas de segurança e rastreabilidade. O Laravel Auditing oferece flexibilidade total para definir o que realmente importa — e isso faz toda a diferença em projetos robustos.

Seja para atender requisitos legais, facilitar o trabalho da equipe administrativa ou apenas garantir histórico confiável de mudanças, customizar os campos auditados é um passo essencial para qualquer aplicação moderna.

Auditando somente ações específicas

Por padrão, o Laravel Auditing registra criação, atualização e exclusão. Mas você pode restringir quais eventos serão auditados com o método getAuditEvents():

public function getAuditEvents(): array
{
    return ['updated']; // Somente quando houver atualização
}

Outras opções válidas: ‘created’, ‘deleted’, ‘restored’.

Auditando apenas em condições específicas

Você pode usar o método shouldAudit() para definir quando o modelo deve ser auditado:

public function shouldAudit(): bool
{
    return auth()->check() && auth()->user()->role === 'admin';
}

Nesse exemplo, apenas alterações feitas por usuários administradores serão registradas.

Definindo quais atributos devem ser auditados

Use os métodos getAuditInclude() e getAuditExclude() para controlar quais campos serão registrados:

public function getAuditInclude(): array
{
    return ['status', 'valor_total']; // Audita apenas estes campos
}

Ou para excluir:

public function getAuditExclude(): array
{
    return ['updated_at']; // Não audita o campo updated_at
}

Ignorando alterações sem mudanças reais

Para evitar registros de auditoria quando os dados não mudaram de fato, verifique se há diferença relevante entre os valores:

public function shouldAudit(): bool
{
    return $this->isDirty(['status', 'valor_total']);
}

Essa abordagem impede registros desnecessários, especialmente em rotinas que atualizam dados com o mesmo valor já existente.

Adicionando lógica condicional para tipos de modelos

Você pode aplicar regras diferentes para cada tipo de modelo:

public function shouldAudit(): bool
{
    if ($this instanceof Pedido) {
        return $this->status !== 'rascunho';
    }

    return true;
}

No exemplo acima, o modelo Pedido só será auditado se o status for diferente de “rascunho”.

Modificando os dados registrados

Se você quiser alterar ou adicionar informações nos registros de auditoria, use o método transformAudit():

public function transformAudit(array $data): array
{
    $data['custom_field'] = 'Exemplo';
    return $data;
}

Você pode, por exemplo, registrar informações como IP do usuário, origem da requisição, nome do sistema, entre outros.

Exemplo prático: auditoria com múltiplas regras

public function shouldAudit(): bool
{
    // Audita somente usuários logados e alterações relevantes
    return auth()->check() && $this->isDirty(['status']) && auth()->user()->role !== 'guest';
}

public function getAuditInclude(): array
{
    return ['status', 'data_pagamento'];
}

public function transformAudit(array $data): array
{
    $data['ip'] = request()->ip();
    return $data;
}

Esse exemplo cobre várias situações práticas: auditoria apenas de mudanças no status, feitas por usuários autenticados que não sejam “guest”, registrando também o IP da requisição.

Personalizar o Laravel Auditing

Personalizar o Laravel Auditing permite adaptar o sistema de auditoria às regras específicas do seu negócio, reduzindo ruído, melhorando a performance e aumentando a eficiência dos registros. Com as estratégias apresentadas, você terá controle total sobre o que, quando e como as alterações devem ser auditadas.

A auditoria personalizada não apenas oferece mais segurança, mas também agrega valor estratégico à sua aplicação, permitindo insights mais relevantes e decisões mais bem fundamentadas.

🔥 Construa seus projetos com a melhor infraestrutura e ainda apoie o DevsBrasil!

Na Hostinger, você encontra hospedagem rápida, segura e com suporte top de linha — ideal para desenvolvedores e empreendedores digitais.

💡 Use o nosso link exclusivo do DevsBrasil e garanta:

✅ Descontos especiais nos planos de hospedagem, e-mail profissional, VPS e criador de sites com IA

✅ Ferramentas otimizadas para performance, com ótimo custo-benefício

✅ Apoio direto à nossa comunidade e ao nosso conteúdo gratuito 💚

👉 Acesse agora com nosso link exclusivo e aproveite os benefícios!

Leave a Comment

Comments

No comments yet. Why don’t you start the discussion?

Deixe um comentário

O seu endereço de e-mail não será publicado. Campos obrigatórios são marcados com *