Configuration Publishing & Customization

This document explains how the default logging configuration is published to a Hyperf application, how to customize it through environment variables, and how to modify published configuration files to suit application-specific needs.

For details on the structure of the configuration file itself, see Configuration File Structure. For information about specific channel types and driver options, see Log Channels & Drivers.

---

Configuration Publishing Mechanism

The hypervel/log package provides a default configuration file that must be published to your Hyperf application before use. This mechanism is handled by the ConfigProvider class, which registers the configuration file for publication through Hyperf's vendor publishing system.

ConfigProvider Publication Definition

The ConfigProvider class defines where the configuration file is sourced from and where it should be published:

src/ConfigProvider.php17-23

Publication Configuration:

Property	Value	Description
id	'config'	Identifier for this publication
description	'The configuration file of log.'	Human-readable description
source	__DIR__ . '/../publish/logging.php'	Source file within package
destination	BASE_PATH . '/config/autoload/logging.php'	Destination in application

Publishing Process

To publish the configuration file to your application, use the Hyperf vendor publish command:

This command copies the file from publish/logging.php in the package directory to config/autoload/logging.php in your application root. Hyperf's autoloader automatically loads files from config/autoload/ at application startup.

Sources: src/ConfigProvider.php1-27 composer.json40-46

---

Environment Variable Configuration

The default configuration file uses environment variables extensively, allowing runtime configuration without modifying code. All environment variable access uses the Hyperf\Support\env() function, which reads from .env files or system environment variables.

Environment Variables Reference

The following environment variables are available in the default configuration:

Environment Variable	Default Value	Usage Location	Purpose
LOG_CHANNEL	'stack'	Top-level default	Sets the default logging channel
LOG_DEPRECATIONS_CHANNEL	'null'	deprecations.channel	Channel for PHP deprecation warnings
LOG_LEVEL	'debug'	Multiple channels	Minimum log level to record
LOG_SLACK_WEBHOOK_URL	none	slack.url	Slack webhook URL for notifications
LOG_PAPERTRAIL_HANDLER	SyslogUdpHandler::class	papertrail.handler	Handler class for Papertrail
PAPERTRAIL_URL	none	papertrail.handler_with	Papertrail service hostname
PAPERTRAIL_PORT	none	papertrail.handler_with	Papertrail service port
LOG_STDOUT_FORMATTER	none	stdout.formatter	Custom formatter for stdout
LOG_STDERR_FORMATTER	none	stderr.formatter	Custom formatter for stderr

Environment Variable Mapping

Sources: publish/logging.php10-142

Common Environment Variable Patterns

Basic Configuration (.env file):

Production Slack Notifications:

Papertrail Integration:

Sources: publish/logging.php24 publish/logging.php67 publish/logging.php81-84 publish/logging.php93-95

---

Customization After Publishing

Once published, the configuration file at config/autoload/logging.php becomes part of your application and can be freely modified to suit your needs.

Modifying Existing Channels

Edit the published configuration file directly to modify channel settings:

Adding Custom Channels

Add new channel definitions to the channels array:

Creating Multi-Channel Stacks

Modify the stack channel to aggregate multiple output destinations:

This configuration writes to both the single file handler and the slack webhook simultaneously.

Sources: publish/logging.php57-141

Customization Workflow

Sources: src/ConfigProvider.php17-23 publish/logging.php12-142

---

Path Configuration

The default configuration uses the BASE_PATH constant to reference application directories. This constant is defined by Hyperf and points to your application's root directory.

Log File Paths

Default log file locations in the published configuration:

Channel	Configuration Key	Default Path
single	path	BASE_PATH . '/runtime/logs/hyperf.log'
daily	path	BASE_PATH . '/runtime/logs/hyperf.log'
emergency	path	BASE_PATH . '/runtime/logs/hyperf.log'

All file-based handlers write to the runtime/logs/ directory by default. The runtime/ directory should be writable by the web server process and is typically excluded from version control.

Path Customization Recommendations

Development Environment:

Production Environment:

Per-Module Logging:

Sources: publish/logging.php66 publish/logging.php73 publish/logging.php139

---

Configuration Precedence and Loading

Hyperf loads configuration files from config/autoload/ during application bootstrap. The published logging.php file merges with any other configuration sources.

Loading Order

Key Points:

1. Configuration files in config/autoload/ are loaded automatically
2. Environment variables are resolved via env() at load time
3. Configuration is cached in production for performance
4. Changes require restart when using configuration caching

Cache Considerations

In production environments with configuration caching enabled, changes to logging.php or .env require clearing the configuration cache:

Without this step, the application continues using cached configuration values.

Sources: src/ConfigProvider.php11-26 publish/logging.php10

---

Advanced Customization Scenarios

Conditional Channel Configuration

Use environment-specific configuration by conditionally modifying channels:

Per-Environment Channel Selection

Dynamic Path Configuration

Sources: publish/logging.php24 publish/logging.php57-141

---

Summary

Configuration publishing and customization follows a clear workflow:

1. Publish the default configuration using vendor:publish hypervel/log
2. Configure environment variables in .env for runtime customization
3. Modify the published config/autoload/logging.php for advanced customization
4. Restart the application (or clear config cache) for changes to take effect

The system provides flexibility through multiple customization layers: environment variables for simple runtime configuration, direct file editing for complex scenarios, and programmatic modification for dynamic behavior.

Sources: src/ConfigProvider.php1-27 publish/logging.php1-142 composer.json40-46