VOOZH about

URL: https://deepwiki.com/hypervel/log

⇱ hypervel/log | DeepWiki

Loading...
Loading...
Menu

Hypervel Log: Overview

Purpose & Scope

This document provides a high-level overview of the hypervel/log package, its architectural design, core components, and integration with the Hyperf framework. It explains the package's role as a PSR-3 compliant logging system that wraps Monolog with Hyperf-specific features like coroutine-safe context management and event dispatching.

For detailed installation instructions, see Installation & Setup. For in-depth explanation of individual components, see Core Architecture. For configuration details, see Configuration.

Sources: composer.json1-48 src/LogManager.php1-659

What is Hypervel Log?

hypervel/log is a logging library designed specifically for Hyperf 3.1 applications. It provides a PSR-3 compliant logging interface while wrapping Monolog 3.1+ as its underlying logging engine. The package extends standard logging capabilities with Hyperf-specific features including coroutine-safe shared context, event dispatching, and seamless dependency injection integration.

The package is distributed under the MIT License (see License Information) and maintained as part of the Hypervel component ecosystem.

Key characteristics:

  • PSR-3 Compliance: Implements Psr\Log\LoggerInterface for broad compatibility
  • Monolog-Powered: Leverages Monolog's mature handler and formatter ecosystem
  • Hyperf-Native: Built for Hyperf 3.1 with coroutine-aware context management
  • Event-Driven: Dispatches MessageLogged events for observability and monitoring
  • Multi-Channel: Supports multiple logging channels with independent configurations

Sources: composer.json1-48 src/LogManager.php29-36

Core Components

The package consists of three primary components that work together to provide logging functionality:

Component Architecture Diagram



Sources: src/LogManager.php1-659 composer.json28-36




Package Components Mapping











































ComponentFileRoleKey Methods/Properties
LogManagersrc/LogManager.phpCentral factory for creating and caching logger channels. Routes requests to appropriate drivers.channel(), driver(), resolve(), createStackDriver(), createSingleDriver(), createDailyDriver()
LoggerReferenced in LogManagerPSR-3 wrapper around Monolog\Logger that adds Hyperf context management and event dispatching.emergency(), alert(), critical(), error(), warning(), notice(), info(), debug()
ParsesLogConfigurationsrc/ParsesLogConfiguration.phpTrait providing configuration parsing utilities for driver creation.parseChannel(), level(), actionLevel()
ConfigProvidersrc/ConfigProvider.phpHyperf service provider that registers DI bindings and publishes configuration files.__invoke() returning dependencies and publish config
MessageLoggedsrc/MessageLogged.phpEvent class dispatched after each log write, containing level, message, and context.Event properties


Sources: src/LogManager.php1-659 composer.json40-43




Architecture Layers


The package is organized into distinct architectural layers, each with specific responsibilities:




Layer 1 - Framework Integration: Provides Hyperf-specific bindings and factory patterns. ConfigProvider registers the LoggerInterface → LogManager binding with the DI container during framework initialization.


Layer 2 - Core Logging System: Contains the main logging logic. LogManager acts as a factory and router, creating Logger instances for different channels. Uses ParsesLogConfiguration trait to interpret configuration arrays.


Layer 3 - Driver System: Polymorphic driver methods that create appropriate Monolog handlers based on channel configuration. Each create*Driver() method corresponds to a configuration driver type.


Layer 4 - Monolog Integration: Wraps Monolog's logging engine, handlers, formatters, and processors. All actual log writing is delegated to Monolog.


Layer 5 - Cross-Cutting Concerns: Event dispatching (MessageLogged), coroutine-safe shared context (Hyperf\Context\Context), and configuration management.


Sources: src/LogManager.php1-659 composer.json28-36




Key Features


1. Channel-Based Logging


The package uses a channel-based architecture where each channel represents an independent logging configuration. Channels are defined in the configuration file and resolved on-demand:




The LogManager::channel() method (src/LogManager.php93-96) retrieves or creates logger instances, caching them in the $channels property (src/LogManager.php48).


Sources: src/LogManager.php93-104 src/LogManager.php48


2. Driver System


Seven built-in drivers provide different logging destinations:























































DriverMethodHandlerUse Case
singlecreateSingleDriver()StreamHandlerSimple file logging to a single file
dailycreateDailyDriver()RotatingFileHandlerDaily rotating log files with retention
stackcreateStackDriver()Multiple handlersAggregate multiple channels into one
slackcreateSlackDriver()SlackWebhookHandlerSend logs to Slack webhooks
syslogcreateSyslogDriver()SyslogHandlerSystem syslog integration
errorlogcreateErrorlogDriver()ErrorLogHandlerPHP error_log() function
monologcreateMonologDriver()Custom handlerMaximum flexibility with any Monolog handler


Additionally, the custom driver (src/LogManager.php201-206) allows user-defined factory functions.


Sources: src/LogManager.php239-363


3. Shared Context Management


The package provides coroutine-safe shared context using Hyperf\Context\Context:




Context is stored in __logger.shared_context (src/LogManager.php424-426) and retrieved via sharedContext() (src/LogManager.php434-437). This is particularly useful in async/coroutine environments where request-scoped data needs to be available across multiple log calls.


Sources: src/LogManager.php418-437


4. Event Dispatching


Every log message triggers a MessageLogged event, enabling observability and monitoring:




This allows external listeners to react to log events for metrics collection, alerting, or custom processing without coupling to the logging implementation. See Event System for details.


Sources: src/LogManager.php86 src/LogManager.php113


5. PSR-3 Compliance


The package fully implements PSR-3 LoggerInterface, providing all eight log level methods:



Each method delegates to the resolved channel, ensuring consistent PSR-3 behavior.


Sources: src/LogManager.php36 src/LogManager.php550-645




Dependency Architecture


The package integrates with multiple external systems:




Dependencies declared in composer.json:



Sources: composer.json28-36




Runtime Flow


The following sequence shows how a typical log operation flows through the system:




Key steps:


    

  1. Resolution Phase (src/LogManager.php109-122): Application requests logger, DI container resolves LogManager, channel configuration is retrieved
    2. 

  2. Creation Phase (src/LogManager.php169-188): LogManager determines driver method, creates Monolog logger with appropriate handlers, wraps in Logger instance
    3. 

  3. Caching (src/LogManager.php112-114): Created logger is cached in $channels array for reuse
    4. 

  4. Logging Phase: Logger retrieves shared context, merges contexts, delegates to Monolog, dispatches event
    5. 



Sources: src/LogManager.php109-122 src/LogManager.php169-188 src/LogManager.php418-437




Configuration-Driven Architecture


The logging system is entirely configuration-driven. Channel behavior is determined by the logging.php configuration file:




The resolve() method (src/LogManager.php169-188) reads the channel configuration via configurationFor() (src/LogManager.php478-481), determines the driver type, and dynamically calls the appropriate create*Driver() method.


For complete configuration documentation, see Configuration.


Sources: src/LogManager.php169-188 src/LogManager.php478-481




Extension Points


The package provides several extension mechanisms:


    

  1. Custom Drivers: Register custom driver factories using extend() (src/LogManager.php504-509)
    2. 

  2. Custom Driver Config: Use driver: 'custom' with a via factory in configuration (src/LogManager.php201-206)
    3. 

  3. Monolog Driver: Use driver: 'monolog' to specify any Monolog handler (src/LogManager.php325-363)
    4. 

  4. Logger Taps: Configure callable taps that modify logger instances (src/LogManager.php127-136)
    5. 



For detailed information on extending the system, see Custom Drivers & Extension.


Sources: src/LogManager.php127-136 src/LogManager.php201-206 src/LogManager.php325-363 src/LogManager.php504-509




Integration with Hyperf Framework


The package integrates with Hyperf through the ConfigProvider class, which:


    

  1. Registers LoggerInterface → LogManager binding in the DI container
    2. 

  2. Publishes default logging.php configuration file
    3. 

  3. Enables automatic service discovery via extra.hyperf.config in composer.json (composer.json40-43)
    4. 



When Hyperf applications bootstrap, they automatically discover and load this configuration provider, making logging services available throughout the application without manual setup.


For integration details, see Hyperf Framework Integration.


Sources: composer.json40-43 src/LogManager.php63-67




Emergency Logging


The system includes an emergency fallback mechanism to prevent white screens of death when the configured logger fails:




The createEmergencyLogger() method (src/LogManager.php149-162) is invoked when logger resolution fails, ensuring the application can always log critical errors even when the logging system itself is misconfigured.


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




Next Steps


    

  • Installation: See Installation & Setup for instructions on adding the package to your Hyperf application
    • 

  • Configuration: See Configuration for detailed configuration options and channel types
    • 

  • Core Components: See Core Architecture for deep dives into LogManager, Logger, and the driver system
    • 

  • Advanced Features: See Advanced Features for event system, contextual logging, and custom extensions
    •