cozmostars/bitacorizable

Trait Bitacorizable - Laravel 10+ para registrar bitácoras automáticas de cualquier modelo

v1.1.2 2025-04-12 09:46 UTC

Requires

• php: ^8.1
• illuminate/support: ^10.0|^11.0|^12.0

MIT

• Said Guerrero

README

Bitacorizable es un Trait para Laravel 10+ que registra automáticamente bitácoras (logs) en la base de datos cuando se crean, actualizan o eliminan modelos Eloquent.

Registra en la tabla bitacoras el historial detallado de los cambios, con los campos modificados y sus valores antes/después.

🔒 Los campos sensibles como password se excluyen automáticamente.

Desarrollado por CozmoStars 🛠

🚀 Instalación

Requiere PHP >= 8.1 y Laravel 10.x, 11.x o 12.x.

composer require cozmostars/bitacorizable

Laravel registrará automáticamente el Service Provider gracias a extra.laravel.providers.

📂 Publicar migración personalizada

Este paquete incluye una migración que puedes publicar y modificar si tu tabla users no usa id como clave primaria (por ejemplo, si usas idUsuario):

php artisan vendor:publish --tag=bitacorizable-migrations

Luego edita la migración publicada y ajusta la clave foránea si es necesario:

$table->foreign('user_id')->references('idUsuario')->on('users');

Y después ejecuta:

php artisan migrate

⚠️ Si no necesitas modificar la migración, puedes simplemente correr php artisan migrate sin publicar nada.

⚙️ Uso

Agrega el trait Bitacorizable a cualquier modelo que quieras auditar:

use CozmoStars\Bitacorizable\Bitacorizable;

class User extends Model
{
    use Bitacorizable;
}

¡Y listo! Cualquier create, update o delete sobre este modelo será registrado automáticamente en la tabla bitacoras.

🧠 ¿Qué registra?

Evento	¿Qué guarda?
created	Todos los campos iniciales del modelo (excluyendo los ignorados)
updated	Solo los campos modificados con su valor antes y después
deleted	Todos los valores del modelo antes de eliminarlo

📄 Ejemplo de log generado

🔹 UPDATE

{
  "name": {
    "antes": "Said Guerrero",
    "después": "Said G."
  },
  "email": {
    "antes": "[e-mail]",
    "después": "[e-mail]"
  }
}

🔹 CREATED

{
  "name": "Said Guerrero",
  "email": "[e-mail]",
  "curp": "GUFA950919HDFRRD05"
}

🔹 DELETED

{
  "id": 14,
  "name": "Empleado Inactivo",
  "email": "[e-mail]"
}

🧩 Tabla bitacoras

Campo	Descripción
id	ID autoincremental
user_id	Usuario que ejecutó la acción (nullable)
model_type	Clase del modelo afectado (ej. App\Models\User)
model_id	ID del modelo afectado
mensaje	Descripción textual (Registro creado, etc.)
codigo	Código del evento (create, update, delete)
log	JSON con los valores previos y posteriores
created_at	Fecha de la acción

❌ Exclusión de campos

Se excluyen por defecto:

• created_at
• updated_at
• password

Puedes agregar más en tu modelo:

protected array $bitacoraCamposIgnorados = [
    'remember_token',
    'api_token',
];

🧬 Relación con el modelo original

El modelo Bitacora define una relación polimórfica model() que te permite acceder al registro afectado:

$bitacora = Bitacora::first();
$registroOriginal = $bitacora->model; // Ej. instancia de User, Post, etc.

✨ Ejemplo de consulta desde tu app

Bitacora::where('model_type', 'App\\Models\\User')
    ->where('model_id', 9)
    ->latest()
    ->get();

📦 Requerimientos

• Laravel 10, 11 o 12
• PHP 8.1 o superior
• Base de datos compatible con jsonb (idealmente PostgreSQL, aunque también funciona con MySQL 5.7+)

💡 Contribuciones

Si deseas aportar mejoras, sugerencias o reportar errores, eres bienvenido a participar en el repositorio:

👉 https://github.com/cozmostars/bitacorizable

📄 Licencia

MIT © 2025 Said Guerrero