Driver System & Handlers

Purpose & Scope

This document details the polymorphic driver system implemented in LogManager, which dynamically creates Monolog handlers based on configuration. It covers the driver resolution mechanism, all built-in driver types (single, daily, stack, slack, syslog, errorlog, monolog, custom), and the handler preparation pipeline that applies formatters and wrappers.

For information about how channels are configured and how the configuration file is structured, see Configuration. For details on extending the system with custom drivers, see Custom Drivers & Extension. For the broader role of LogManager as a channel factory, see LogManager: Channel Factory & Manager.

---

Driver Resolution System

The driver system uses a convention-based polymorphic dispatch pattern. When LogManager needs to create a logger for a channel, it examines the driver key in the channel's configuration and dynamically routes to the appropriate creation method.

Resolution Flow

Sources: src/LogManager.php169-188

The resolve method performs this dispatch at src/LogManager.php169-188:

1. Retrieves channel configuration via configurationFor src/LogManager.php478-481
2. Checks if a custom creator exists for the driver in $this->customCreators src/LogManager.php177-179
3. Builds method name as 'create' . ucfirst($config['driver']) . 'Driver' src/LogManager.php181
4. Checks if method exists and calls it src/LogManager.php183-185
5. Throws InvalidArgumentException if driver is unsupported src/LogManager.php187

---

Built-in Drivers Overview

The system provides eight built-in driver types, each creating specific Monolog handlers:

Driver	Method	Primary Handler	Purpose	Config File Example
single	createSingleDriver	StreamHandler	Single log file	publish/logging.php64-69
daily	createDailyDriver	RotatingFileHandler	Daily rotating files	publish/logging.php71-77
stack	createStackDriver	Aggregates multiple handlers	Multiple output channels	publish/logging.php58-62
slack	createSlackDriver	SlackWebhookHandler	Slack webhook notifications	publish/logging.php79-86
syslog	createSyslogDriver	SyslogHandler	System syslog integration	publish/logging.php120-125
errorlog	createErrorlogDriver	ErrorLogHandler	PHP error_log()	publish/logging.php127-131
monolog	createMonologDriver	User-specified handler	Maximum flexibility	publish/logging.php88-98 publish/logging.php100-107
custom	createCustomDriver	Factory-created	User-defined factory	N/A

Sources: src/LogManager.php199-363 publish/logging.php57-141

---

Driver Details

Single Driver

Sources: src/LogManager.php238-253

Creates a StreamHandler for writing to a single file. Configuration keys:

• path (required): File path for logs
• level: Minimum log level (default: debug) src/ParsesLogConfiguration.php38-47
• bubble: Whether to bubble to parent handlers (default: true)
• permission: File permissions (default: null)
• locking: Whether to lock file during writes (default: false)
• replace_placeholders: Enable PSR-3 placeholder replacement (default: false)

When replace_placeholders is true, adds PsrLogMessageProcessor to processors src/LogManager.php252

Sources: src/LogManager.php238-253 publish/logging.php64-69

---

Daily Driver

Sources: src/LogManager.php258-270

Creates a RotatingFileHandler for daily rotating log files. Configuration keys:

• path (required): Base file path
• days: Number of files to retain (default: 7) src/LogManager.php263
• level: Minimum log level (default: debug)
• bubble: Whether to bubble (default: true)
• permission: File permissions (default: null)
• locking: Whether to lock file (default: false)
• replace_placeholders: Enable PSR-3 placeholder replacement (default: false)

The handler automatically appends date suffixes to the filename and removes old files.

Sources: src/LogManager.php258-270 publish/logging.php71-77

---

Stack Driver

Sources: src/LogManager.php211-234

Aggregates multiple channels into a single logger. Each log message is sent to all configured channels. The driver:

1. Accepts channels as string (comma-separated) or array src/LogManager.php213-215
2. Retrieves handlers from each channel via $this->channel($channel)->getHandlers() src/LogManager.php217-221
3. Retrieves processors from each channel via $this->channel($channel)->getProcessors() src/LogManager.php223-227
4. If ignore_exceptions is true, wraps handlers in WhatFailureGroupHandler to suppress handler exceptions src/LogManager.php229-231

Configuration keys:

• channels (required): Array or comma-separated string of channel names
• channel: Optional channel name for the stack itself
• ignore_exceptions: Suppress handler exceptions (default: false)

Sources: src/LogManager.php211-234 publish/logging.php58-62

---

Slack Driver

Sources: src/LogManager.php275-291

Creates a SlackWebhookHandler for sending logs to Slack. Configuration keys:

• url (required): Slack webhook URL
• channel: Slack channel (default: null)
• username: Bot username (default: 'Hyperf') src/LogManager.php281
• attachment: Send as attachment (default: true)
• emoji: Bot emoji (default: ':boom:') src/LogManager.php283
• short: Use short attachment format (default: false)
• context: Include context data (default: true)
• level: Minimum log level (default: debug)
• bubble: Whether to bubble (default: true)
• exclude_fields: Array of fields to exclude (default: [])
• replace_placeholders: Enable PSR-3 placeholder replacement (default: false)

Sources: src/LogManager.php275-291 publish/logging.php79-86

---

Syslog Driver

Sources: src/LogManager.php296-305

Creates a SyslogHandler for system syslog integration. Configuration keys:

• facility: Syslog facility constant (default: LOG_USER) src/LogManager.php301
• level: Minimum log level (default: debug)
• replace_placeholders: Enable PSR-3 placeholder replacement (default: false)

The ident parameter (syslog identifier) is derived from app.name config, snake-cased with hyphens src/LogManager.php300

Sources: src/LogManager.php296-305 publish/logging.php120-125

---

Errorlog Driver

Sources: src/LogManager.php310-318

Creates an ErrorLogHandler for writing to PHP's error_log(). Configuration keys:

• type: Error log type constant (default: ErrorLogHandler::OPERATING_SYSTEM) src/LogManager.php314
• level: Minimum log level (default: debug)
• replace_placeholders: Enable PSR-3 placeholder replacement (default: false)

Sources: src/LogManager.php310-318 publish/logging.php127-131

---

Monolog Driver

Sources: src/LogManager.php325-363

Provides maximum flexibility by allowing any Monolog handler class. Configuration keys:

• handler (required): Fully-qualified handler class name, must implement HandlerInterface src/LogManager.php327-331
• with: Constructor parameters for handler (merged with level) src/LogManager.php343-347
• handler_with: Alias for with src/LogManager.php346
• processors: Array of processor class names, each must implement ProcessorInterface src/LogManager.php333-341
• Standard handler config: formatter, formatter_with, action_level, etc.

The handler is instantiated via $this->app->make($config['handler'], $with) src/LogManager.php350 Processors support nested configuration with processor and with keys src/LogManager.php354-356

Sources: src/LogManager.php325-363 publish/logging.php88-98 publish/logging.php100-118

---

Custom Driver

Sources: src/LogManager.php199-206

Allows custom logger factories. Configuration keys:

• via (required): Callable or class name that creates a logger

The via value can be:

• A Closure or callable: Used directly src/LogManager.php203
• A class name: Resolved via DI container src/LogManager.php203

The factory receives the full channel configuration and must return a LoggerInterface src/LogManager.php205

Sources: src/LogManager.php199-206

---

Handler Preparation Pipeline

All handlers pass through a preparation pipeline that applies formatters and wrappers:

Sources: src/LogManager.php380-403 src/LogManager.php368-375

Action Level Wrapping

If action_level is configured, the handler is wrapped in FingersCrossedHandler src/LogManager.php382-390:

• Buffers log records until action_level is reached
• Only writes buffered records if threshold is hit
• Useful for reducing noise while capturing context for errors

Configuration keys:

• action_level: Trigger level (e.g., 'error') src/LogManager.php384
• stop_buffering: Stop buffering after trigger (default: true) src/LogManager.php388

Sources: src/LogManager.php382-390 src/ParsesLogConfiguration.php54-63

Formatter Application

For handlers implementing FormattableHandlerInterface src/LogManager.php392-393:

1. If no formatter config: Apply default LineFormatter src/LogManager.php396-397 src/LogManager.php408-411
2. If formatter = 'default': Skip formatting src/LogManager.php398
3. Otherwise: Instantiate custom formatter via $this->app->make($config['formatter'], $config['formatter_with'] ?? []) src/LogManager.php399

The default LineFormatter is configured with:

• format: null (uses default format)
• dateFormat: $this->dateFormat ('Y-m-d H:i:s') src/LogManager.php58
• allowInlineLineBreaks: true
• ignoreEmptyContextAndExtra: true
• includeStacktraces: true

Sources: src/LogManager.php392-403 src/LogManager.php408-411 src/LogManager.php58

---

Configuration to Code Mapping

This diagram shows how configuration keys map to specific code paths and handler instantiation:

Sources: src/LogManager.php169-188 src/LogManager.php238-363 src/LogManager.php380-403 src/ParsesLogConfiguration.php38-71

Key Configuration Keys

Common configuration keys processed by the system:

Config Key	Trait/Method	Purpose	File Reference
level	ParsesLogConfiguration::level()	Minimum log level	src/ParsesLogConfiguration.php38-47
action_level	ParsesLogConfiguration::actionLevel()	Buffering trigger level	src/ParsesLogConfiguration.php54-63
name	ParsesLogConfiguration::parseChannel()	Monolog channel name	src/ParsesLogConfiguration.php68-71
formatter	LogManager::prepareHandler()	Custom formatter class	src/LogManager.php396-399
formatter_with	LogManager::prepareHandler()	Formatter constructor args	src/LogManager.php399
replace_placeholders	Driver methods	Enable PsrLogMessageProcessor	src/LogManager.php252
bubble	Handler constructors	Propagate to parent handlers	src/LogManager.php246
stop_buffering	prepareHandler()	Stop buffering after action level	src/LogManager.php388
tap	LogManager::tap()	Logger customization hooks	src/LogManager.php127-136

Sources: src/LogManager.php127-411 src/ParsesLogConfiguration.php38-71