Download the PHP package mongoose-studio/phobos-framework-logger without Composer

Phobos Framework - Logger

Librería satélite opt-in de logging estructurado para Phobos Framework. Logs JSON line-delimited con contexto de traza automático (trace_id/request_id), redacción de datos sensibles y writers intercambiables. Implementa PSR-3 sin arrastrar Monolog ni ninguna otra dependencia pesada — fiel al minimalismo del núcleo, que a propósito no trae logger.

Características

• 📋 PSR-3 completo - Psr\Log\LoggerInterface, interpola placeholders {clave}, valida niveles
• 🧱 JSON estructurado - una línea = un objeto JSON, listo para Loki/agentes de logs (patrón K8s)
• 🔗 Contexto de traza - trace_id/request_id inyectados en cada registro desde un LogContext request-scoped
• 🌐 W3C Trace Context - adopta el traceparent entrante (Kong/OTel) y lo propaga saliente con traceParent()
• 🕵️ Redacción de secretos - enmascara claves sensibles (password, token, authorization, ...) y patrones sueltos (JWT, PAN)
• 🚦 Access-log integrado - request.handled con método, path, status y duración; nivel según status (4xx=warning, 5xx=error)
• 🖥️ Writers intercambiables - stdout (prod), pretty (dev, coloreado), file, memory (tests), null
• 💥 Excepciones expandidas - context['exception'] con un Throwable se expande a {class, message, file, line, trace}
• 🧪 Testeable por diseño - DI por constructor en todo; MemoryWriter para afirmar logs en tests
• 🚫 Cero magia - sin facades, sin estado estático: la forma canónica de Phobos

Instalación

Dependencias

• mongoose-studio/phobos-framework ^3.1
• psr/log ^3.0
• PHP >= 8.4

Uso

1. Registrar el provider (módulo raíz)

2. Middleware global (contexto de traza + access-log)

Primero en la cadena, para que todo lo demás ya loguee con contexto:

3. Loguear desde un service (inyección por constructor)

Depende de LoggerInterface (PSR-3), no de la clase concreta: testeable y reemplazable.

4. Excepciones no manejadas (entry point)

5. Propagar la traza hacia afuera

Formato del registro

tenant_id/actor_id se promueven a la raíz: se fijan una vez en el LogContext (p. ej. en el middleware de auth) y salen en todos los registros del request.

Configuración (config/logging.php)

Todo es opcional; sin archivo, los defaults funcionan.

Redacción

Sin PII ni secretos en los logs, en ningún ambiente. Dos mecanismos:

• Por clave (recursivo, insensible a mayúsculas, por contención): password, card_number, reset_token_hash... → ••••••
• Por patrón (sobre strings sueltos): JWT y PAN de tarjeta se enmascaran aunque la clave no delate nada

Testing (en tu proyecto)

Bindea el writer de memoria y afirma sobre lo logueado:

Relación con el Observer del core

El Observer (trace(), Observer::dumpFormatted()) es una línea de tiempo en memoria para depurar un request puntual; no persiste ni sale del proceso. Este Logger es para producción: estructurado, persistente (stdout → Loki) y correlacionado por trace_id. Son complementarios.

Tests de la librería

Licencia

Este proyecto está licenciado bajo la Licencia MIT - ver el archivo LICENSE para más detalles.

Autor

Marcel Rojas
[email protected]
Mongoose Studio

Contribuciones

Las contribuciones son bienvenidas. Por favor:

1. Fork el proyecto
2. Crea una rama para tu feature (git checkout -b feature/amazing-feature)
3. Commit tus cambios (git commit -m 'Add amazing feature')
4. Push a la rama (git push origin feature/amazing-feature)
5. Abre un Pull Request

Phobos Framework by Mongoose Studio