Hyperf Framework Integration

Purpose

This document explains how the hypervel/log package integrates with the Hyperf framework's core systems. It covers the integration mechanisms that allow the logging system to work seamlessly within Hyperf applications, including dependency injection binding, service registration, and factory pattern adaptation.

For detailed information about service registration and ConfigProvider, see ConfigProvider & Service Registration. For factory adapters implementation details, see Factory Adapters. For configuration structure and options, see Configuration.

Integration Architecture

The package integrates with Hyperf through three primary mechanisms:

1. Dependency Injection Binding: The ConfigProvider class registers the PSR-3 LoggerInterface to resolve to the LogManager implementation
2. Service Discovery: Hyperf's automatic service discovery system detects and loads the ConfigProvider at application startup
3. Factory Adaptation: The LogFactoryAdapter extends Hyperf's native LoggerFactory to provide compatibility with existing Hyperf logging patterns

Integration Components

Diagram: Integration Architecture Overview

Sources: src/ConfigProvider.php1-27 src/Adapter/HyperfLogFactory.php1-19 src/Adapter/LogFactoryAdapter.php1-23

Dependency Injection Integration

The package uses Hyperf's dependency injection container to provide logging services throughout the application. The core binding is established in ConfigProvider:

Binding	Implementation	Scope
Psr\Log\LoggerInterface	Hypervel\Log\LogManager	Singleton

When application code requests LoggerInterface through constructor injection or via $container->get(LoggerInterface::class), the container resolves this to a LogManager instance. The LogManager then acts as a factory, creating and caching channel-specific Logger instances.

Resolution Flow

Diagram: Dependency Injection Resolution Flow

Sources: src/ConfigProvider.php14-16

The LogManager receives the ConfigInterface instance through constructor injection, allowing it to read logging configuration from the application's config files. This design follows Hyperf's convention of using constructor injection for dependencies.

Service Discovery and Registration

Hyperf automatically discovers and registers the package's services through the ConfigProvider class. The discovery process occurs during application bootstrap:

1. Discovery: Hyperf scans composer.json files for packages with extra.hyperf.config entries
2. Loading: The framework instantiates the ConfigProvider and invokes it
3. Registration: The provider returns an array containing dependency bindings and publishable resources

ConfigProvider Structure

The ConfigProvider returns two key sections:

dependencies
├── LoggerInterface::class => LogManager::class

publish
└── [
 'id' => 'config',
 'description' => 'The configuration file of log.',
 'source' => __DIR__ . '/../publish/logging.php',
 'destination' => BASE_PATH . '/config/autoload/logging.php'
 ]

The dependencies section establishes the LoggerInterface binding, while the publish section defines the default configuration file that can be published to the application.

Sources: src/ConfigProvider.php9-26

Factory Pattern Adaptation

Hyperf applications often use the LoggerFactory pattern for creating logger instances. To maintain compatibility with this pattern, the package provides HyperfLogFactory and LogFactoryAdapter.

Adapter Pattern Implementation

Diagram: Factory Adapter Pattern

Sources: src/Adapter/HyperfLogFactory.php10-18 src/Adapter/LogFactoryAdapter.php10-23

The HyperfLogFactory implements the invokable factory pattern, creating LogFactoryAdapter instances with the container and config interface injected. The LogFactoryAdapter extends Hyperf's LoggerFactory base class but delegates to the LogManager for actual logger creation.

Method Delegation

The LogFactoryAdapter overrides two methods from the base LoggerFactory:

Method	Parameters	Behavior
make()	$name, $group	Ignores parameters, returns default channel logger
get()	$name, $group	Ignores parameters, returns default channel logger

Both methods call $container->get(LoggerInterface::class)->channel(), which resolves to LogManager and retrieves the default channel logger. The $name and $group parameters are not applicable in this implementation, as the package uses channel-based configuration instead.

Sources: src/Adapter/LogFactoryAdapter.php12-22

Integration with Hyperf Systems

The package integrates with several Hyperf subsystems beyond basic dependency injection:

Configuration System Integration

The package reads logging configuration through Hyperf\Contract\ConfigInterface, accessing the logging configuration namespace. The configuration structure follows Hyperf conventions with:

• Top-level default key for the default channel name
• channels array defining available log channels
• Support for environment variable substitution using env() helper

Context System Integration

The logging system uses Hyperf\Context\Context for coroutine-safe shared context storage. This allows request-scoped logging context to be maintained across async operations without explicit passing. See Contextual Logging for details.

Event System Integration

Loggers dispatch MessageLogged events through Hyperf's PSR-14 event dispatcher, enabling event-driven monitoring and metrics collection. See Event System for details.

Container Resolution Patterns

Application code can access loggers through multiple patterns:

Pattern 1: Direct Injection

constructor(LoggerInterface $logger)

Injects the LogManager instance, allowing channel selection via $logger->channel('name').

Pattern 2: Container Resolution

$logger = $container->get(LoggerInterface::class)

Explicitly resolves the logger from the container at runtime.

Pattern 3: Factory Pattern

$logger = $container->get(LoggerFactory::class)->get()

Uses the LogFactoryAdapter for compatibility with Hyperf's logging conventions.

All three patterns ultimately resolve to the same underlying LogManager instance, as it is registered as a singleton in the container.

Integration Lifecycle

Diagram: Integration Lifecycle States

The integration lifecycle follows Hyperf's standard service provider pattern:

1. Service Discovery: Hyperf scans installed packages during application bootstrap
2. Config Provider Load: The framework loads and invokes ConfigProvider
3. Binding Registration: Dependencies are registered with the DI container
4. Container Ready: The container is fully initialized and ready to resolve services
5. First Request: Application code first requests LoggerInterface
6. Logger Resolution: Container creates the LogManager singleton
7. Subsequent Requests: All future requests receive the same cached instance

Sources: src/ConfigProvider.php1-27

Framework Version Compatibility

The package requires Hyperf framework version 3.1 or higher. Key dependencies include:

Component	Version	Purpose
hyperf/config	^3.1	Configuration system access
hyperf/contract	^3.1	Framework interface contracts
hyperf/context	^3.1	Coroutine-safe context storage
hyperf/stringable	^3.1	String formatting utilities
hyperf/collection	^3.1	Collection data structures

These dependencies ensure the package integrates correctly with Hyperf's core systems and maintains compatibility with the framework's conventions.