README

BaseModel para Laravel 11, 12 e 13 com CRUD Eloquent-first, auditoria automática, operações em lote e bulk update.

Instalação

composer require gsebastiao/laravel-model-audit
php artisan vendor:publish --tag=model-audit-migrations
php artisan migrate

Publicar config (opcional):

php artisan vendor:publish --tag=model-audit-config

Criar um Model

php artisan make:audit-model Produto --table=produtos --soft-deletes

Ou manualmente:

use CodeBuilder\BaseModel\BaseModel;

class Produto extends BaseModel
{
    protected $table = 'produtos';
    protected $fillable = ['nome', 'preco', 'categoria_id'];

    public function getResolveMap(): array
    {
        return [
            'categoria_id' => self::getResolveMap(label: 'Categoria', table: 'categorias', column: 'nome'),
            'ativo'        => self::getResolveMap(type: 'alias', label: 'Situação'),
        ];
    }
}

CRUD

Insert

// Simples
$id = Produto::insertData(['nome' => 'Cadeira', 'preco' => 150.00]);

// Com resolveMap para auditoria legível
$id = Produto::insertData([
    'data'       => ['nome' => 'Cadeira', 'categoria_id' => 3],
    'resolveMap' => Produto::getResolveMap(label: 'Categoria', table: 'categorias', column: 'nome'),
]);

Update (Eloquent — respeita timestamps, mutators e eventos)

// Por ID
Produto::updateData(5, ['preco' => 200.00]);

// Por condições
Produto::updateData(['ativo' => 0], ['preco' => 0]);

Bulk Update (Query Builder — 1 query, sem mutators)

// Atualiza milhares de registos numa única query
// updated_at é gerido automaticamente
Produto::bulkUpdate(['categoria_id' => 3], ['ativo' => 0]);

Delete

Produto::deleteData(5);              // soft delete
Produto::deleteData(5, purge: true); // delete permanente
Produto::deleteData(['ativo' => 0]); // por condição

Update or Insert

$result = Produto::updateOrInsert(
    conditions: ['sku' => 'ABC-001'],
    data: ['nome' => 'Cadeira Pro', 'preco' => 299.00]
);
// ['action' => 'inserted'|'updated', 'id' => 12]

Operações em Lote

updateDataBatch

Produto::updateDataBatch([
    ['conditions' => ['id' => 1], 'data' => ['preco' => 100]],
    ['conditions' => ['id' => 2], 'data' => ['preco' => 200]],
]);

deleteDataBatch

Produto::deleteDataBatch([
    ['categoria_id' => 1, 'ativo' => 0],
    ['categoria_id' => 2, 'ativo' => 0],
]);

upsertData

Produto::upsertData(
    dataBatch:    [['data' => ['sku' => 'A1', 'preco' => 10]], ...],
    uniqueFields: ['sku'],
);

Auditoria

Todas as operações são auditadas automaticamente na tabela app_tables_audits.

// Desativar pontualmente
Produto::disableAudit();
Produto::updateData(5, ['preco' => 0]);
Produto::enableAudit();

// Tabela de auditoria personalizada
Produto::setAuditTable('minha_tabela_audits');

// Consultar auditoria de um registo
$audit = Produto::audits('produtos', ['id' => 5, 'page' => 1, 'limit' => 10]);

ResolveMap — tipos disponíveis

// direct — busca label numa tabela (FK)
'user_id' => self::getResolveMap(label: 'Usuário', table: 'users', column: 'name')

// direct com scope — filtra por campo adicional
'status_code' => self::getResolveMap(
    label:  'Status',
    table:  'app_tables_status',
    key:    'code',
    column: 'name',
    scope:  ['table_name' => 'produtos'],
)

// join — resolve via tabelas intermediárias
'estado_id' => self::getResolveMap(
    type:  'join',
    joins: [
        ['table' => 'estados', 'key' => 'id'],
        ['table' => 'paises', 'on' => ['paises.id', '=', 'estados.pais_id'], 'column' => 'nome', 'label' => 'País'],
    ],
)

// alias — renomeia o campo sem tocar no banco
'ativo' => self::getResolveMap(type: 'alias', label: 'Situação')

Gerador de Código Sequencial

$codigo = Produto::generate(
    table:    'produtos',
    column:   'codigo',
    template: '{prefix}-{year}-{number}',
    placeholders: ['{prefix}' => 'PROD'],
);
// → 'PROD-2025-001'

Config (config/model-audit.php)

Compatibilidade

Licença

MIT