Core Architecture

Purpose and Scope

This page explains the core architectural components of the hypervel/log package and how they work together to provide a flexible logging system. It covers the three primary classes (LogManager, Logger, and the ParsesLogConfiguration trait), their relationships, and the two-phase logging process.

For detailed information about specific subsystems, see:

• Driver system and handler creation: Driver System & Handlers
• LogManager's channel factory responsibilities: LogManager: Channel Factory & Manager
• Logger's PSR-3 wrapper implementation: Logger: PSR-3 Wrapper

---

Core Components

The logging system consists of three primary components that work together to provide channel-based logging with Hyperf framework integration:

Component	File	Primary Responsibility
LogManager	src/LogManager.php36-658	Factory that creates, caches, and routes logger instances based on configuration
Logger	src/Logger.php17-272	PSR-3 compliant wrapper around Monolog loggers with Hyperf-specific features (context management, event dispatching)
ParsesLogConfiguration	src/ParsesLogConfiguration.php10-72	Trait that provides configuration parsing utilities for translating string levels to Monolog constants

Sources: src/LogManager.php36-658 src/Logger.php17-272 src/ParsesLogConfiguration.php10-72

---

Component Relationships

The following diagram illustrates how the three core components relate to each other and to external dependencies:

Sources: src/LogManager.php36-67 src/LogManager.php109-122 src/Logger.php17-26

---

Two-Phase Logging Process

The logging system operates in two distinct phases: channel resolution and message logging.

Phase 1: Channel Resolution

When application code requests a logger channel, LogManager performs the following steps:

The channel resolution logic is implemented in src/LogManager.php109-122 The get() method checks the channels array cache src/LogManager.php48 before calling resolve() src/LogManager.php169-188 to create a new logger instance.

Sources: src/LogManager.php109-122 src/LogManager.php169-188 src/LogManager.php236-270

Phase 2: Message Logging

Once a Logger instance is obtained, logging a message involves context merging, delegation to Monolog, and event dispatching:

The logging logic is in src/Logger.php136-144 Context retrieval happens at src/Logger.php177-180 and event dispatching occurs at src/Logger.php204-210

Sources: src/Logger.php136-144 src/Logger.php177-180 src/Logger.php204-210

---

Architecture Patterns

Factory Pattern

LogManager implements the Factory pattern for creating logger instances. The factory uses a polymorphic driver system where the resolve() method src/LogManager.php169-188 examines the driver configuration key and dynamically invokes the corresponding creation method:

Configuration	Method Called	Monolog Handler Created
driver: single	createSingleDriver() src/LogManager.php239-253	StreamHandler
driver: daily	createDailyDriver() src/LogManager.php258-270	RotatingFileHandler
driver: stack	createStackDriver() src/LogManager.php211-234	Multiple handlers aggregated
driver: slack	createSlackDriver() src/LogManager.php275-291	SlackWebhookHandler
driver: syslog	createSyslogDriver() src/LogManager.php296-305	SyslogHandler
driver: errorlog	createErrorlogDriver() src/LogManager.php310-318	ErrorLogHandler
driver: monolog	createMonologDriver() src/LogManager.php325-363	User-specified handler
driver: custom	createCustomDriver() src/LogManager.php201-206	Custom factory callback

The factory caches created instances in the channels property src/LogManager.php48 to avoid recreating loggers for the same channel.

Sources: src/LogManager.php169-188 src/LogManager.php48 src/LogManager.php239-363

Decorator Pattern

Logger wraps a Monolog logger instance and decorates it with additional functionality:

1. Context Management: Adds Hyperf Context-based contextual logging src/Logger.php151-180
2. Event Dispatching: Fires MessageLogged events on every log call src/Logger.php204-210
3. Message Formatting: Handles arrays, Jsonable, and Arrayable objects src/Logger.php218-231

The underlying Monolog logger is stored in the logger property src/Logger.php23 and accessed via delegation. All PSR-3 methods (src/Logger.php33-117) ultimately call writeLog() src/Logger.php136-144 which delegates to the wrapped logger while adding the decorations.

Sources: src/Logger.php23 src/Logger.php136-144 src/Logger.php151-210 src/Logger.php218-231

Trait-Based Configuration Parsing

The ParsesLogConfiguration trait src/ParsesLogConfiguration.php10-72 provides shared configuration parsing logic that LogManager uses src/LogManager.php38 This trait defines:

• levels array mapping string levels to Monolog constants src/ParsesLogConfiguration.php15-24
• level() method converting config level strings to integers src/ParsesLogConfiguration.php38-47
• actionLevel() method for FingersCrossedHandler configuration src/ParsesLogConfiguration.php54-63
• parseChannel() method extracting channel names src/ParsesLogConfiguration.php68-71

This pattern allows configuration parsing logic to be reused without inheritance.

Sources: src/ParsesLogConfiguration.php10-72 src/LogManager.php38

---

Integration Points with Hyperf Framework

Dependency Injection Container

LogManager receives the DI container via constructor injection src/LogManager.php63-67:

The container is used throughout the class to:

• Retrieve ConfigInterface for reading logging configuration src/LogManager.php66
• Resolve custom driver factories src/LogManager.php203
• Instantiate tap classes for logger customization src/LogManager.php132
• Create Monolog handlers and processors src/LogManager.php350 src/LogManager.php355

Sources: src/LogManager.php63-67 src/LogManager.php132 src/LogManager.php203 src/LogManager.php350-355

Hyperf Context System

Both LogManager and Logger use Hyperf's Context class for coroutine-safe, request-scoped data storage:

Logger context (per-logger instance):

• Key: __logger.context src/Logger.php153 src/Logger.php167 src/Logger.php179
• Methods: withContext() src/Logger.php151-158 withoutContext() src/Logger.php165-170 getContext() src/Logger.php177-180

Shared context (across all loggers):

• Key: __logger.shared_context src/LogManager.php424 src/LogManager.php436 src/LogManager.php462
• Methods: shareContext() src/LogManager.php418-429 sharedContext() src/LogManager.php434-437 flushSharedContext() src/LogManager.php460-465

This allows middleware or early request handlers to call $logManager->shareContext(['request_id' => '...']), and all subsequent log calls automatically include that context without explicit passing.

Sources: src/Logger.php151-180 src/LogManager.php418-465

PSR-14 Event Dispatcher

Logger accepts an optional EventDispatcherInterface src/Logger.php24 and dispatches a MessageLogged event for every log call src/Logger.php204-210:

This enables event-driven monitoring, metrics collection, and alerting without modifying logging code. The dispatcher is injected when LogManager creates Logger instances src/LogManager.php84-87 src/LogManager.php113 src/LogManager.php158-161

Sources: src/Logger.php22-26 src/Logger.php204-210 src/LogManager.php84-87 src/LogManager.php113

---

Code Entity Mapping

The following diagram maps architectural concepts to their specific code implementations:

Sources: src/LogManager.php48 src/LogManager.php109-122 src/LogManager.php169-188 src/LogManager.php211-270 src/LogManager.php418-437 src/Logger.php151-180 src/Logger.php204-210 src/ParsesLogConfiguration.php38-71

---

Emergency Fallback Mechanism

When logger creation fails, LogManager provides an emergency fallback to prevent application crashes. The get() method wraps resolve() in a try-catch block src/LogManager.php111-122:

The emergency logger src/LogManager.php149-162 writes to php://stdout with debug level, ensuring critical errors are logged even when the configured logging system fails.

Sources: src/LogManager.php111-122 src/LogManager.php149-162