PHPackages                             mongoose-studio/phobos-framework-logger - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. mongoose-studio/phobos-framework-logger

ActiveLibrary

mongoose-studio/phobos-framework-logger
=======================================

Phobos Framework Logger - Structured JSON logging with trace context (PSR-3)

1.0.0(1mo ago)022MITPHPPHP >=8.4

Since Jul 18Pushed 1mo agoCompare

[ Source](https://github.com/mongoose-studio/phobos-framework-logger)[ Packagist](https://packagist.org/packages/mongoose-studio/phobos-framework-logger)[ RSS](/packages/mongoose-studio-phobos-framework-logger/feed)WikiDiscussions main Synced 2w ago

READMEChangelog (1)Dependencies (3)Versions (2)Used By (0)

Phobos Framework - Logger
=========================

[](#phobos-framework---logger)

[![PHP Version](https://camo.githubusercontent.com/64a069e7c3b8fcd6db65758dfcf6884b8224069f53a516ac85d62117a230d469/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d253345253344253230382e342d626c7565)](https://www.php.net/)[![License](https://camo.githubusercontent.com/784362b26e4b3546254f1893e778ba64616e362bd6ac791991d2c9e880a3a64e/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d4d49542d677265656e2e737667)](LICENSE.txt)[![PSR-3](https://camo.githubusercontent.com/859c80101bf1854b24b976bf0be2faa9f9d3f0c9ac22bbffa2c7fd02e29ec904/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5053522d2d332d636f6d706c69616e742d626c756576696f6c6574)](https://www.php-fig.org/psr/psr-3/)[![Phobos Framework](https://camo.githubusercontent.com/3a5d96f30c70e3a8057bd2f3dca9b77ecfd208b665cb58de1986b03ad08e462f/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f50686f626f732d4672616d65776f726b2d6f72616e6765)](https://github.com/mongoose-studio/phobos-framework)

   ![Phobos Framework](https://raw.githubusercontent.com/mongoose-studio/phobos-framework/main/phobos-banner-dark.png)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
---------------

[](#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
-----------

[](#instalación)

```
composer require mongoose-studio/phobos-framework-logger
```

### Dependencias

[](#dependencias)

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

Uso
---

[](#uso)

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

[](#1-registrar-el-provider-módulo-raíz)

```
public function providers(): array {
    return [AppServiceProvider::class, LoggerServiceProvider::class];
}
```

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

[](#2-middleware-global-contexto-de-traza--access-log)

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

```
Phobos::init(ROOT, APPLICATION)
    ->loadEnvironment()->loadConfig()
    ->middleware(RequestLogContextMiddleware::class)
    ->middleware(CorsMiddleware::class)
    ->bootstrap(ApiModule::class)
    ->run()->send();
```

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

[](#3-loguear-desde-un-service-inyección-por-constructor)

```
use Psr\Log\LoggerInterface;

class PostService {
    public function __construct(private LoggerInterface $log) {}   // autowiring

    public function publish(object $data): array {
        $this->log->info('post.publishing', ['kind' => $data->kind]);

        try {
            // ...
        } catch (\Throwable $e) {
            $this->log->error('post.publish_failed', ['exception' => $e]);
            throw $e;   // nunca tragarse la excepción
        }

        return ['status' => 'ok'];
    }
}
```

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

### 4. Excepciones no manejadas (entry point)

[](#4-excepciones-no-manejadas-entry-point)

```
try {
    Phobos::init(ROOT, APPLICATION)->/* ... */->run()->send();
} catch (\Throwable $e) {
    inject(Psr\Log\LoggerInterface::class)->critical('unhandled.exception', ['exception' => $e]);
    // ... luego la traducción a JSON del template
}
```

### 5. Propagar la traza hacia afuera

[](#5-propagar-la-traza-hacia-afuera)

```
// A una llamada HTTP saliente (Guzzle) o al sobre de un evento del bus:
$headers['traceparent'] = logContext()->traceParent();
```

Formato del registro
--------------------

[](#formato-del-registro)

```
{
  "timestamp":  "2026-07-15T12:00:00.123Z",
  "level":      "info",
  "service":    "core-social",
  "message":    "request.handled",
  "trace_id":   "4bf92f3577b34da6a3ce929d0e0e4736",
  "request_id": "0af7651916cd43dd8448eb211c80319c",
  "tenant_id":  null,
  "actor_id":   null,
  "context":    { "method": "GET", "path": "/v1/feed", "status": 200, "duration_ms": 42.1 }
}
```

`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.

```
logContext()->setActorId($userId);
logContext()->setTenantId($clientId);
```

Configuración (`config/logging.php`)
------------------------------------

[](#configuración-configloggingphp)

Todo es opcional; sin archivo, los defaults funcionan.

```