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

Register the service provider:

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

Configure in config/logging.php:

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

Usage

use EzPhp\Logging\Log;

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('info', 'Something happened');

Drivers

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

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

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

License

MIT — Andreas Uretschnig