README

Módulo de auditoría y logs desacoplado para PHP 7.4+ (compatible con PHP 8).
Implementa una arquitectura basada en interfaces (SOLID) y soporta fallback automático en caso de fallas del storage principal.

📦 Instalación

# Desde Packagist (público)
composer require vendor/audit-logger

Si el paquete está en un repositorio privado, agrega la sección repositories a tu composer.json:

{
  "repositories": [
    {"type": "vcs", "url": "git@github.com:mycompany/audit-logger.git"}
  ],
  "require": {"vendor/audit-logger": "^1.0"}
}

Luego ejecutá composer install.

⚙️ Configuración básica

<?php
declare(strict_types=1);

use AuditLogger\AuditLogger;
use AuditLogger\Storage\FileStorage;
use AuditLogger\Storage\DatabaseStorage;
use PDO;

// 1️⃣ Driver principal (ejemplo: MySQL)
$pdo = new PDO(
    'mysql:host=localhost;dbname=logs;charset=utf8mb4',
    'db_user',
    'db_pass',
    [PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION]
);
$primary = new DatabaseStorage($pdo, 'audit_logs');

// 2️⃣ Driver de fallback (archivo plano)
$fallback = new FileStorage(__DIR__.'/storage/audit.log');

// 3️⃣ Instanciar el logger
$logger = new AuditLogger($primary, $fallback);

// (Opcional) Asociar el ID del usuario autenticado
// $logger->setUserId($authUserId);

🛠️ Uso del logger

// Acción exitosa
$logger->log(
    actionType: 'AUTH.LOGIN',
    status:     'SUCCESS',
    description:'Usuario autenticado',
    payload:    ['email' => 'juan@example.com'], // el payload será sanitizado automáticamente
    attemptedId: 'juan@example.com'               // opcional: identificador intentado
);

// Acción fallida (se guardará en fallback si la BD falla)
$logger->log(
    actionType: 'AUTH.LOGIN_ATTEMPT',
    status:     'FAILED',
    description:'Login fallido (contraseña incorrecta)',
    payload:    ['email' => 'juan@example.com', 'password' => 'secreto'],
    attemptedId: 'juan@example.com'
);

¿Qué hace el logger internamente?

1. Contexto – LogContext captura IP y User‑Agent y sanitiza el payload usando una lista negra (password, token, cc_number, etc.).
2. Entidad – LogEntity representa el registro con fecha, UUID y datos opcionales.
3. Almacenamiento – LogStorageInterface define save(LogEntity $log): bool. Se proveen dos implementaciones:
   • DatabaseStorage (PDO + tabla audit_logs).
   • FileStorage (escribe líneas de texto en un archivo).
4. Fallback – Si primaryStorage->save() lanza una excepción, el logger agrega la traza al mensaje y escribe en fallbackStorage sin propagar la excepción (fallo silencioso).

🧪 Tests

El proyecto está cubierto con PHPUnit (versión 9.6, compatible con PHP 7.4).

composer install   # instala dev‑dependencias
vendor/bin/phpunit tests/

Los tests verifican:

• Correcta generación de UUID y campos.
• Sanitización de payload.
• Funcionalidad de FileStorage y DatabaseStorage usando mocks.
• Comportamiento de fallback y de silenciamiento total.

📜 Licencia

MIT – siéntete libre de usar, modificar y redistribuir.

🤝 Contribuir

1. Forkea el repositorio.
2. Crea una rama feature/… o bugfix/….
3. Ejecutá los tests (composer test).
4. Abre un Pull Request describiendo el cambio.

¡Listo! Ahora tenés un logger robusto, probado y listo para ser instalado en cualquier proyecto PHP 7.4+. Si necesitás agregar un nuevo driver (Redis, S3, etc.) solo implementá LogStorageInterface y pasalo al constructor de AuditLogger.