Configuration Management

This document covers the configuration system in Hypervel, including environment variable handling, configuration file structure, the ConfigProvider pattern for Hyperf integration, and how Hypervel overrides Hyperf framework configurations to provide Laravel-compatible behavior.

For information about service provider registration and bootstrapping lifecycle, see Service Providers and Bootstrapping. For global helper functions including config(), see Facades and Global Helper Functions.

---

Configuration Architecture Overview

Hypervel's configuration system bridges Laravel-style configuration files with Hyperf's ConfigInterface. The system loads configuration from multiple sources and transforms it to ensure compatibility with both Hyperf's internal systems and Hypervel's Laravel-compatible APIs.

Sources: src/foundation/src/Providers/FoundationServiceProvider.php35-128 src/foundation/src/ConfigProvider.php1-47

---

Configuration File Structure

Configuration files are stored in config/autoload/ and are automatically loaded by Hyperf. Hypervel publishes a base app.php configuration file and expects additional standard Laravel configuration files.

Standard Configuration Files

File	Purpose	Key Settings
app.php	Application settings	name, env, timezone, debug, stdout_log_level, editor
database.php	Database connections	default, connections, migrations
cache.php	Cache stores	Cache driver configurations
queue.php	Queue connections	Queue driver configurations
broadcasting.php	Broadcasting drivers	WebSocket and event broadcasting
server.php	HTTP server	Server configuration, kernels

Publishing Configuration

The foundation package provides a publishable app.php configuration:

Sources: src/foundation/src/ConfigProvider.php37-44

Configuration File Format

Configuration files return PHP arrays:

Sources: src/foundation/src/ConfigProvider.php38-43

---

Hyperf Configuration Override System

Hypervel overrides Hyperf's configuration structure to align it with Laravel conventions. This happens during the service provider registration phase in FoundationServiceProvider.

Configuration Override Process

Sources: src/foundation/src/Providers/FoundationServiceProvider.php108-128

Configuration Mappings

The following table shows how Hypervel configuration keys map to Hyperf's expected structure:

Hypervel Config	Hyperf Config	Transformation
app.name	app_name	Direct copy
app.env	app_env	Direct copy
app.stdout_log_level	StdoutLoggerInterface::class . '.log_level'	Namespaced key
database.connections	databases	Direct copy
database.default	databases.default	Resolved connection config
database.migrations	databases.migrations	Migration path
database.redis	redis	Options merged per connection

Sources: src/foundation/src/Providers/FoundationServiceProvider.php110-119

Redis Configuration Transformation

Redis configuration requires special transformation to merge connection-specific options with global options:

The transformation ensures that global Redis options (like prefix, serializer) are applied to all connection configurations.

Sources: src/foundation/src/Providers/FoundationServiceProvider.php130-141

---

Database Configuration Management

Default Connection Resolution

The framework sets the default database connection during the boot phase:

Sources: src/foundation/src/Providers/FoundationServiceProvider.php101-106

Database Connection Structure

Database configuration uses Hyperf's database configuration format:

• connections: Array of connection configurations (mysql, pgsql, sqlite, etc.)
• default: Name of the default connection
• migrations: Path to migration files (default: 'migrations')

The databases.default Hyperf config key receives the full connection array for the default connection, while databases.migrations specifies the migration directory.

Sources: src/foundation/src/Providers/FoundationServiceProvider.php114-117

---

Middleware Configuration Processing

Middleware configuration undergoes sorting and merging with global middleware from HTTP kernels.

Middleware Configuration Flow

The process:

1. Load middleware config: Get per-server middleware arrays from config
2. Sort middleware: Apply MiddlewareManager::sortMiddlewares() for priority ordering
3. Extract global middleware: Check server.kernels config for HTTP kernel classes implementing MiddlewareContract
4. Merge: Prepend global middleware to sorted server-specific middleware
5. Store: Write final configuration back to ConfigInterface

Sources: src/foundation/src/Providers/FoundationServiceProvider.php143-162

---

Application Settings Configuration

Timezone and Encoding

The framework applies timezone and encoding settings during the boot phase:

Sources: src/foundation/src/Providers/FoundationServiceProvider.php49-54 src/foundation/src/Providers/FoundationServiceProvider.php171-178

Debug Mode and Logging

Debug mode affects console output verbosity:

The app.stdout_log_level configuration controls Hyperf's stdout logger verbosity.

Sources: src/foundation/src/Providers/FoundationServiceProvider.php44-46 src/foundation/src/Providers/FoundationServiceProvider.php113

Editor Configuration for Debugging

The app.editor configuration enables IDE integration for dump source resolution in CliDumper and HtmlDumper.

Supported Editor Formats

Built-in Editor Formats

The ResolvesDumpSource trait defines href formats for common editors:

Editor	Href Template
phpstorm	phpstorm://open?file={file}&line={line}
vscode	vscode://file/{file}:{line}
vscode-insiders	vscode-insiders://file/{file}:{line}
sublime	subl://open?url=file://{file}&line={line}
atom	atom://core/open/file?filename={file}&line={line}
cursor	cursor://file/{file}:{line}
idea	idea://open?file={file}&line={line}
nova	nova://core/open/file?filename={file}&line={line}

Sources: src/foundation/src/Concerns/ResolvesDumpSource.php16-33 src/foundation/src/Concerns/ResolvesDumpSource.php146-171

---

Configuration Access at Runtime

ConfigInterface Resolution

All configuration access ultimately goes through Hyperf's ConfigInterface:

Sources: src/foundation/src/Providers/FoundationServiceProvider.php41 src/foundation/src/Providers/FoundationServiceProvider.php103

Configuration in Service Providers

Service providers access configuration through the injected ConfigInterface:

Sources: src/foundation/src/Providers/FoundationServiceProvider.php35-43

Configuration Helper Function

The global config() helper provides convenient access to configuration values (documented in Facades and Global Helper Functions):

---

Configuration and Environment Variables

Environment variables are typically accessed using the env() helper within configuration files. The .env file is loaded by Hyperf during application bootstrap.

Environment Variable Reloading

The ReloadDotenvAndConfig listener reloads environment variables and configuration when the server reloads:

Sources: src/foundation/src/ConfigProvider.php29

---

Configuration Provider Pattern

Hypervel components use the ConfigProvider pattern to integrate with Hyperf's dependency injection and configuration systems.

ConfigProvider Structure

The Foundation package's ConfigProvider:

• Registers DI bindings for ApplicationInterface and process title listener
• Registers error handling and configuration reload listeners
• Provides console commands (AboutCommand, ConfigShowCommand, ServerReloadCommand, VendorPublishCommand)
• Publishes the base app.php configuration file

Sources: src/foundation/src/ConfigProvider.php20-46

---

Configuration Best Practices

Configuration Loading Order

1. Hyperf loads all config/autoload/*.php files
2. Configuration is merged into ConfigInterface
3. FoundationServiceProvider registers and overrides Hyperf configs
4. Service providers boot and can access final configuration
5. Application runs with merged configuration

Compiled View Path Configuration

The dumper system requires the compiled view path for source resolution:

This enables the CliDumper and HtmlDumper to resolve original blade file paths from compiled view files.

Sources: src/foundation/src/Providers/FoundationServiceProvider.php190

Configuration in Tests

Test classes can mock configuration using the Repository class:

Sources: tests/Foundation/Console/CliDumperTest.php49-55 tests/Foundation/Http/HtmlDumperTest.php49-55