README

Logging module for the ez-php framework — structured logging with pluggable drivers, minimum-level filtering, JSON formatting, request context injection, and automatic exception logging.

Requirements

PHP 8.5+
ez-php/framework 0.*

Installation

composer require ez-php/logging

Setup

$app->register(\EzPhp\Logging\LogServiceProvider::class);

Configure in config/logging.php:

return [
    'driver'    => getenv('LOG_DRIVER') ?: 'file', // file | stdout | syslog | null | json | stack
    'path'      => getenv('LOG_PATH') ?: 'storage/logs',
    'min_level' => getenv('LOG_LEVEL') ?: '',      // DEBUG|INFO|WARNING|ERROR|CRITICAL — empty = all
    'json_inner'=> getenv('LOG_JSON_INNER') ?: 'stdout', // inner driver when driver=json
    'stack'     => ['file', 'stdout'],              // used when driver=stack
];

Usage

use EzPhp\Logging\Log;
use EzPhp\Logging\LogLevel;

Log::debug('Cache miss', ['key' => 'users.all']);
Log::info('User registered', ['id' => 42]);
Log::warning('Rate limit approaching', ['remaining' => 5]);
Log::error('Payment failed', ['order' => 'ORD-99']);
Log::critical('Database unreachable');

// Generic level dispatch
Log::log(LogLevel::INFO, 'Something happened');

Drivers

Driver	Description
`file`	Appends to `{path}/app-YYYY-MM-DD.log` (daily rotation)
`stdout`	`debug`/`info`/`warning` → stdout · `error`/`critical` → stderr
`syslog`	System logger (syslog/journald) via PHP's `openlog()`/`syslog()`; ident and facility from `logging.syslog.*`
`null`	Discards all entries — useful in tests
`json`	Decorator: serialises entries as JSON and forwards to an inner driver
`stack`	Decorator: fans each call out to multiple inner drivers simultaneously

Wrap any driver with a minimum-level filter by setting LOG_LEVEL:

LOG_DRIVER=file
LOG_LEVEL=WARNING   # drops DEBUG and INFO entries

Syslog

LOG_DRIVER=syslog
LOG_SYSLOG_IDENT=my-app      # program name in the log (default ez-php)
LOG_SYSLOG_FACILITY=local0  # user (default), daemon, auth, local0 … local7

Levels map to LOG_DEBUG, LOG_INFO, LOG_WARNING, LOG_ERR and LOG_CRIT; a non-empty context is JSON-encoded onto the message. syslog can also be a stack or json inner driver. Remote syslog (RFC 5424 over UDP) is out of scope — use ez-php/log-transport for shipping.

JSON structured logging

LOG_DRIVER=json
LOG_JSON_INNER=stdout

Each entry is written as a single JSON line:

{"timestamp":"2026-03-21T12:00:00+00:00","level":"info","message":"tick.event","context":{"user_id":5}}

Stack driver

Write to multiple destinations simultaneously:

LOG_DRIVER=stack

// config/logging.php
return [
    'driver' => 'stack',
    'stack'  => ['file', 'stdout'],
];

Request context middleware

RequestContextMiddleware injects request_id, ip, method, and path into every log entry produced during a request:

$app->middleware(\EzPhp\Logging\RequestContextMiddleware::class);

The middleware wraps the current logger in a ContextualLogger and restores the original logger in finally.

Exception logging

LogServiceProvider automatically wraps the ExceptionHandler with LoggingExceptionHandler, so all unhandled exceptions are logged at error level (with exception class, code, file, and line) before the response is rendered. No extra configuration needed.

Log format (file/stdout)

[2026-03-15 12:00:00] INFO: User registered {"id":42}
[2026-03-15 12:00:01] ERROR: Payment failed {"order":"ORD-99"}

Classes

Class	Description
`LoggerInterface`	Contract: `log()`, `debug()`, `info()`, `warning()`, `error()`, `critical()`
`LogLevel`	Backed enum: `DEBUG\|INFO\|WARNING\|ERROR\|CRITICAL`; `severity()`, `isAtLeast()`
`FileDriver`	Appends to daily-rotated log files; creates directory on demand
`StdoutDriver`	stdout for debug/info/warning, stderr for error/critical
`SyslogDriver`	System logger via stdlib `syslog()`; level → `LOG_*` priority, context JSON-appended
`NullDriver`	No-op — discards all entries
`JsonDriver`	Decorator: serialises entries as JSON, forwards to inner driver
`StackDriver`	Decorator: fans calls out to a list of inner drivers
`MinLevelDriver`	Decorator: drops entries below a configured minimum severity
`ContextualLogger`	Decorator: merges a fixed context array into every log call
`RequestContextMiddleware`	Injects request_id/ip/method/path context for the duration of a request
`Log`	Static façade backed by a managed `LoggerInterface` singleton
`LoggingExceptionHandler`	Decorator: logs exceptions at error level, then delegates to inner handler
`LogServiceProvider`	Config-driven driver binding; wraps `ExceptionHandler`; wires `Log` façade

License

MIT — Andreas Uretschnig

ez-php / logging

Package info

Security

Statistics