aporteweb / laravel-guachiman
Guardia de seguridad para laravel
This package is auto-updated.
Last update: 2025-08-05 11:23:35 UTC
README
Un registrador de actividad simple y flexible para tus aplicaciones de Laravel. "Guachimán" es un término coloquial en algunos países de habla hispana para un vigilante o guardián, que es exactamente lo que hace este paquete: vigila y registra las actividades en tu aplicación.
Instalación
Puedes instalar el paquete a través de composer:
composer require aporteweb/laravel-guachiman
Nota: Si estás trabajando en un entorno de desarrollo y necesitas la última versión, puedes usar
dev-main
:composer require aporteweb/laravel-guachiman:dev-main
El proveedor de servicios se registrará automáticamente gracias al auto-descubrimiento de paquetes de Laravel.
Publicar archivos
Debes publicar la migración para crear la tabla de registro de actividad:
php artisan vendor:publish --provider="AporteWeb\Guachiman\Providers\GuachimanServiceProvider" --tag="migrations"
Después, ejecuta las migraciones:
php artisan migrate
Si deseas personalizar la configuración, puedes publicar el archivo de configuración:
php artisan vendor:publish --provider="AporteWeb\Guachiman\Providers\GuachimanServiceProvider" --tag="config"
Esto creará un archivo config/guachiman.php
en tu aplicación donde puedes cambiar el nombre de la tabla y la conexión de la base de datos.
Uso
1. Registro automático de eventos de modelo
Para registrar automáticamente los eventos created
, updated
y deleted
de tus modelos de Eloquent, solo necesitas usar el trait AporteWeb\Guachiman\Traits\LogsChanges
en tu modelo.
use Illuminate\Database\Eloquent\Model; use AporteWeb\Guachiman\Traits\LogsChanges; class Product extends Model { use LogsChanges; // ... }
Especificar qué atributos registrar
Por defecto, todos los atributos que cambien se registrarán en el evento updated
. Puedes especificar qué atributos quieres registrar añadiendo una propiedad $loggable
a tu modelo.
class Product extends Model { use LogsChanges; protected $loggable = ['name', 'price']; // ... }
Añadir etiquetas personalizadas a los atributos
Puedes definir etiquetas personalizadas para los atributos registrados. Estas etiquetas se guardarán en el JSON de propiedades, lo que puede ser útil para mostrar los cambios de una manera más amigable en la interfaz de usuario.
Para ello, añade una propiedad pública $loggableLabels
a tu modelo:
class Product extends Model { use LogsChanges; protected $loggable = ['name', 'price', 'stock_quantity']; public $loggableLabels = [ 'name' => 'Nombre del Producto', 'price' => 'Precio', 'stock_quantity' => 'Cantidad en Stock', ]; // ... }
El registro de actividad para una actualización de stock_quantity
se vería así:
{ "changes": [ { "field": "stock_quantity", "label": "Cantidad en Stock", "new_value": "10", "old_value": "15" } ] }
Personalizar el nombre del causante del evento
Por defecto, el campo causer_name
se llena con el atributo name
del usuario autenticado. Si deseas usar un atributo diferente o una combinación de atributos (por ejemplo, nombre y apellido), puedes añadir un accesor getResolvedDescriptionAttribute
a tu modelo User
.
// En tu modelo App\Models\User class User extends Authenticatable { // ... /** * Devuelve el nombre completo del usuario. */ public function getResolvedDescriptionAttribute() { return $this->fullname; // o $this->first_name . ' ' . $this->last_name; } }
2. Registro manual de actividad
También puedes registrar actividades manualmente usando la función de ayuda activity()
. Esto es útil para registrar acciones que no están directamente relacionadas con un evento de modelo.
Uso básico
activity()->log('El usuario ha exportado un informe de ventas.');
Métodos encadenados
El helper proporciona varios métodos para añadir más contexto a tu registro de actividad.
activity() ->causedBy($user) // El usuario que causó el evento (opcional, se infiere el usuario autenticado) ->performedOn($someModel) // El modelo sobre el que trata el evento ->withProperties(['key' => 'value']) // Añade propiedades personalizadas en formato JSON ->log('Ha ocurrido algo'); // La descripción del evento
Ejemplo práctico:
use App\Models\Product; use App\Models\User; $user = User::find(1); $product = Product::find(1); activity() ->causedBy($user) ->performedOn($product) ->withProperties(['action' => 'export', 'format' => 'pdf']) ->log("El producto {$product->name} fue exportado"); /* Esto creará un registro de actividad con: - causer: el usuario con id 1 - subject: el producto con id 1 - properties: {"action": "export", "format": "pdf"} - description: "El producto NombreDelProducto fue exportado" */
Referencias
Esta libreria esta inspirada en el paquete spatie/laravel-activitylog
Licencia
Este paquete se distribuye bajo la licencia MIT. Consulta el archivo LICENSE
para más detalles.