Installation & Setup

This document provides step-by-step instructions for installing the hypervel/log package in a Hyperf 3.1 application, publishing the default configuration, and verifying the installation. For detailed information about configuring log channels and drivers, see Configuration. For information about how the package integrates with Hyperf's dependency injection system, see ConfigProvider & Service Registration.

Prerequisites

Before installing hypervel/log, ensure your environment meets the following requirements:

Requirement	Version	Purpose
PHP	^8.2	Minimum PHP version required
Hyperf Framework	~3.1.0	Core framework compatibility
Monolog	^3.1	Underlying logging engine
hypervel/support	^0.3	Shared utilities package

Sources: composer.json29-35

The package automatically installs the following Hyperf components as dependencies:

• hyperf/config - Configuration management
• hyperf/stringable - String manipulation utilities
• hyperf/contract - Framework contracts and interfaces
• hyperf/collection - Data collection handling

Sources: composer.json30-35

Installation via Composer

Installation Flow

Sources: composer.json1-47 src/ConfigProvider.php9-27

Installation Command

Install the package using Composer:

This command:

1. Downloads the hypervel/log package and its dependencies
2. Registers the Hypervel\Log namespace with PSR-4 autoloading to the src/ directory
3. Triggers Hyperf's automatic service discovery via the extra.hyperf.config configuration

Sources: composer.json23-26 composer.json40-46

Configuration Publishing

Publishing the Configuration File

After installation, publish the default configuration file:

When prompted, select the config option to publish the logging configuration.

Sources: src/ConfigProvider.php17-24

Configuration File Locations

Sources: src/ConfigProvider.php21-22

The publishing process copies the default configuration from the package's publish/ directory to your application's config/autoload/ directory:

Source	Destination	Purpose
vendor/hypervel/log/publish/logging.php	config/autoload/logging.php	Default logging configuration with pre-configured channels

Sources: src/ConfigProvider.php21-22

Published Configuration Contents

The published logging.php file contains:

Configuration Key	Default Value	Description
default	env('LOG_CHANNEL', 'stack')	Default channel name used for logging
deprecations	Array with channel and trace settings	Channel for PHP deprecation warnings
channels	Array of channel configurations	Pre-configured log channels (stack, single, daily, slack, etc.)

Sources: publish/logging.php12-142

The default configuration includes these pre-configured channels:

• stack - Aggregates multiple channels
• single - Single log file
• daily - Rotating daily log files
• slack - Slack webhook notifications
• papertrail - Papertrail remote logging
• stdout - Standard output stream
• stderr - Standard error stream
• syslog - System syslog
• errorlog - PHP error log
• null - Discards all logs
• emergency - Emergency fallback channel

Sources: publish/logging.php57-141

Automatic Service Registration

Dependency Injection Bindings

Sources: src/ConfigProvider.php13-16

The ConfigProvider class automatically registers the logging system with Hyperf's dependency injection container. No manual registration is required.

Automatic Registration Details:

Binding	Implementation	Purpose
Psr\Log\LoggerInterface	Hypervel\Log\LogManager	Binds the PSR-3 standard interface to the LogManager implementation

Sources: src/ConfigProvider.php14-15

When Hyperf's service discovery scans the installed packages, it:

1. Detects the extra.hyperf.config key in composer.json41-42
2. Loads the Hypervel\Log\ConfigProvider class
3. Invokes the __invoke() method to retrieve service registrations
4. Registers the LoggerInterface binding in the DI container

Sources: composer.json40-43 src/ConfigProvider.php11-26

Verification

Verifying Installation

To verify the package is correctly installed and configured, inject the logger into a controller or service:

After making a request to this controller, check the log file at runtime/logs/hyperf.log (or the path configured in your logging.php file) to confirm the message was logged.

Sources: publish/logging.php66 src/ConfigProvider.php15

Installation Checklist

Step	Verification
Package installed	composer.json contains hypervel/log in require section
Configuration published	config/autoload/logging.php file exists
Service registered	Injecting LoggerInterface succeeds without errors
Logging works	Test log message appears in configured destination

Sources: composer.json1-47 src/ConfigProvider.php1-27 publish/logging.php1-142

Directory Structure After Installation

After successful installation and configuration publishing, your application structure should include:

project-root/
├── config/
│ └── autoload/
│ └── logging.php # Published configuration
├── runtime/
│ └── logs/
│ └── hyperf.log # Default log file location
└── vendor/
 └── hypervel/
 └── log/
 ├── src/
 │ ├── ConfigProvider.php
 │ ├── LogManager.php
 │ └── Logger.php
 └── publish/
 └── logging.php # Source configuration template

Sources: src/ConfigProvider.php22 publish/logging.php66

Environment Variables

The published configuration supports environment-based customization without modifying the configuration file. The following environment variables are available:

Environment Variable	Default	Description
LOG_CHANNEL	stack	Default log channel to use
LOG_LEVEL	debug	Minimum log level to record
LOG_DEPRECATIONS_CHANNEL	null	Channel for PHP deprecation warnings
LOG_SLACK_WEBHOOK_URL	-	Slack webhook URL for notifications
LOG_PAPERTRAIL_HANDLER	SyslogUdpHandler::class	Handler class for Papertrail
PAPERTRAIL_URL	-	Papertrail service URL
PAPERTRAIL_PORT	-	Papertrail service port
LOG_STDOUT_FORMATTER	-	Formatter for stdout channel
LOG_STDERR_FORMATTER	-	Formatter for stderr channel

Sources: publish/logging.php24 publish/logging.php38 publish/logging.php67 publish/logging.php81 publish/logging.php91-95 publish/logging.php103 publish/logging.php113

Configure these variables in your .env file to customize logging behavior without modifying the configuration file directly.