README

Monolog integration bundle for SymPress WordPress kernel applications.

The package provides a Composer-powered WordPress MU plugin that registers a Monolog logger, channel loggers, configurable handlers, processors, and WordPress-specific logging hooks through the SymPress kernel service container.

Installation

composer require sympress/monolog-bundle

The package requires PHP 8.5, sympress/kernel, monolog/monolog, and psr/log.

Features

Default PSR-3 logger service exposed as logger and Psr\Log\LoggerInterface
Channel logger support through monolog.logger tags and Monolog attributes
Configurable handlers for stream, rotating file, fingers crossed, grouped, filtered, console, mail, syslog, socket, Slack webhook, and related Monolog handler types
Handler-to-channel routing with inclusive and exclusive channel rules
Tagged processor registration with handler or channel targeting
WordPress runtime context processor
Kernel throwable, WordPress database, and HTTP API logging hooks
Profiler bridge that forwards buffered Monolog records to SymPress Profiler

Usage

When the SymPress kernel discovers the package, it registers SymPress\MonologBundle\MonologBundle and loads monolog-bundle/monolog-bundle.php as the MU plugin entry point.

<?php

use Psr\Log\LoggerInterface;

final readonly class ImportOrders
{
    public function __construct(
        private LoggerInterface $logger,
    ) {
    }

    public function run(): void
    {
        $this->logger->info('Import started.');
    }
}

Configuration

The package ships with a rotating file handler (14 daily files, mode 0600 and locking) and a profiler buffer handler. The automatic level is debug for local/development/dev/test and warning otherwise. Empty/false/null logs_dir disables the default file sink. Project configuration can override handlers and channels through the Monolog extension.

monolog:
    channels:
        - security
    handlers:
        main:
            type: fingers_crossed
            action_level: error
            handler: nested
        nested:
            type: stream
            path: '%kernel.logs_dir%/%kernel.environment%.log'
            level: debug
            nested: true
        security_file:
            type: stream
            path: '%kernel.logs_dir%/security.log'
            channels: [security]

Services can request channel-specific loggers by using Monolog's WithMonologChannel attribute or the monolog.logger service tag.

See docs/handlers.md for the supported handler types, required keys, defaults, and generated service IDs.

Development

composer install
composer qa

Use composer cs:fix to apply automatic style fixes.

License

This package is licensed under GPL-2.0-or-later.

Output redaction and profiler collection

Compiled loggers and processing handlers redact messages/context/extra after interpolation and configured processors. External non-processing handlers are wrapped at their logger/standard-handler references without replacing their typed application service. Credential fields, SQL/error context, exception messages, URL userinfo/query values, Bearer/Basic credentials and DSNs are scrubbed. Arrays, strings and exception chains are bounded; arbitrary Stringable objects are never invoked. Applications should still use generic event messages: a free-form secret with no identifying syntax cannot be reliably recognized by a redactor. Custom handlers must not append fresh sensitive data after receiving the sanitized record.

The profiler handler consults the profiler's optional ProfileGate before running processors or normalizers. Missing or closed gate discards the record; authorized collection keeps a bounded FIFO SplQueue. Early WordPress boot stays closed until the existing profiler authorization lifecycle can evaluate the user. The sympress_profiler_log_entries filter and entry shape are unchanged.

Native handler processing evaluates the gate once. When a Logger has its own processors, Monolog may first ask whether the handler accepts the record, then evaluate authorization again after those processors. That separate preflight decision is not cached: processors cannot retain authorization after closing the gate. Minimum levels and bubbling retain native Monolog behavior.

sympress / monolog-bundle

Package info

Security

Statistics