README

High-performance, zero-dependency PSR-3 logger for the MonkeysLegion PHP framework. Built natively in PHP 8.4 with no Monolog dependency.

Features

Feature	Status
PSR-3 Compliant	✅ Full `Psr\Log\LoggerInterface`
Zero External Dependencies	✅ Only `psr/log` interface
11 Handlers	Stream, Rotating, Syslog, ErrorLog, Console, Null, Buffer, FingersCrossed, Deduplication, Group, Sampling
2 Formatters	Line (template), JSON (structured)
6 Processors	UID, Memory, Introspection, Timestamp, Redact, Environment
PHP 8.4 Features	Property hooks, asymmetric visibility, backed enum, match expressions
Context Stacking	`pushContext()` / `popContext()` for scoped context
Log Metrics	Real-time per-level counters with `$errorRate`
Sensitive Data Redaction	Automatic GDPR/PCI-safe redaction
Probabilistic Sampling	Sample a % of debug logs in production
FingersCrossed (Black Box)	Buffer until error, then flush full context
Deduplication	Suppress repeated log entries

Installation

composer require monkeyscloud/monkeyslegion-logger

Quick Start

use MonkeysLegion\Logger\Logger;
use MonkeysLegion\Logger\Handler\StreamHandler;
use MonkeysLegion\Logger\LogLevel;

// Create a logger with a file handler
$logger = new Logger(
    handlers: [new StreamHandler('logs/app.log', LogLevel::Debug)],
    channelName: 'app',
);

$logger->info('User {name} logged in', ['name' => 'Jorge']);
$logger->error('Payment failed', ['order_id' => 42]);

$logger->close();

Using the LogManager

use MonkeysLegion\Logger\LogManager;

$manager = new LogManager([
    'default' => 'stack',
    'channels' => [
        'stack' => [
            'driver' => 'stack',
            'channels' => ['daily', 'console'],
        ],
        'daily' => [
            'driver' => 'daily',
            'path' => 'logs/app.log',
            'level' => 'debug',
            'max_files' => 14,
        ],
        'console' => [
            'driver' => 'console',
            'level' => 'warning',
            'colorize' => true,
        ],
    ],
]);

$logger = $manager->channel(); // default = stack
$logger->info('Application started');

// Switch channels
$apiLogger = $manager->channel('daily');
$apiLogger->error('API timeout');

Handlers

StreamHandler

Writes to files or PHP streams with LOCK_EX for concurrency safety.

$handler = new StreamHandler('logs/app.log', LogLevel::Warning);

RotatingFileHandler

Daily log rotation with automatic cleanup of old files.

$handler = new RotatingFileHandler('logs/app.log', maxFiles: 14);

ConsoleHandler

ANSI-colored output to stderr/stdout.

$handler = new ConsoleHandler(LogLevel::Debug, colorize: true);

BufferHandler

Defers I/O by buffering records in memory. Flushes on close or overflow.

$handler = new BufferHandler($innerHandler, bufferLimit: 100);

FingersCrossedHandler

Black box recorder. Buffers everything silently. When an error arrives, flushes the entire buffer — giving full debug context for production errors.

$handler = new FingersCrossedHandler($innerHandler, LogLevel::Error);

DeduplicationHandler

Suppresses repeated identical log entries within a time window.

$handler = new DeduplicationHandler($innerHandler, deduplicationWindow: 60);

SamplingHandler

Novel. Probabilistic sampling — logs only a percentage of non-error records.

$handler = new SamplingHandler($innerHandler, sampleRate: 0.01); // 1%
// Errors always pass through regardless of sample rate

GroupHandler

Dispatches to multiple handlers simultaneously.

$handler = new GroupHandler([$fileHandler, $consoleHandler]);

Processors

RedactProcessor (Novel)

Automatically redacts sensitive fields from context data.

use MonkeysLegion\Logger\Processor\RedactProcessor;

$processor = new RedactProcessor();
// Automatically redacts: password, token, api_key, secret, credit_card, ssn, etc.

$logger = new Logger(
    handlers: [$handler],
    processors: [$processor],
);

$logger->info('Login', ['user' => 'jorge', 'password' => 'secret']);
// Output: {"context":{"user":"jorge","password":"********"}}

Other Processors

use MonkeysLegion\Logger\Processor\UidProcessor;          // Request correlation ID
use MonkeysLegion\Logger\Processor\MemoryProcessor;       // Memory usage & peak
use MonkeysLegion\Logger\Processor\IntrospectionProcessor; // Call site (file, line)
use MonkeysLegion\Logger\Processor\TimestampProcessor;    // Microsecond timestamps
use MonkeysLegion\Logger\Processor\EnvironmentProcessor;  // Hostname, PHP version, SAPI

Context Stacking

$logger->pushContext(['request_id' => 'abc-123']);

$logger->info('Processing started');  // Includes request_id
$logger->info('Step 2 complete');     // Includes request_id

$logger->popContext();

$logger->info('Done'); // No request_id

Log Metrics

$metrics = $logger->getMetrics();

echo $metrics->totalCount;   // Total log entries
echo $metrics->errorRate;    // Ratio of errors to total (0.0–1.0)
echo $metrics->countFor(LogLevel::Error); // Count per level

LogLevel Enum

use MonkeysLegion\Logger\LogLevel;

$level = LogLevel::Error;
$level->priority();       // 4
$level->isError();        // true
$level->label();          // 'ERROR'
$level->syslogSeverity(); // LOG_ERR

LogLevel::fromPsr3('fatal'); // LogLevel::Critical

Changelog

2.0.0 — Complete Rebuild

BREAKING CHANGE: Full API redesign. All v1 classes removed.

Architecture: Replaced Monolog-dependent design with native, zero-dependency Handler/Formatter/Processor architecture
Core Types: LogLevel backed enum, immutable LogRecord VO, LogMetrics VO
13 Handlers: Stream, RotatingFile, Syslog, ErrorLog, Console, Null, Buffer, FingersCrossed, Deduplication, Group, Sampling
2 Formatters: LineFormatter (template-based), JsonFormatter (structured JSON Lines)
7 Processors: UID, Memory, Introspection, Timestamp, Redact, Environment
Novel Features: Probabilistic sampling, sensitive data redaction, context stacking, real-time log metrics
PHP 8.4: Property hooks, asymmetric visibility, backed enums, match expressions
DI-First: LogManager with config-driven channel resolution and custom driver extension
Tests: 96 tests, 171 assertions

Requirements

PHP 8.4+
psr/log ^3.0

License

MIT

monkeyscloud / monkeyslegion-logger

Maintainers

Package info

Statistics

Security