Configuration Management

Purpose and Scope

This document provides an overview of the configuration management system in Hypervel Testbench. It covers the structure and usage of configuration files, environment variable management, and how configuration data flows from YAML sources through to the application container.

For details on how the Bootstrapper loads and processes configuration, see Bootstrapper Lifecycle. For information on specific configuration provider registration, see Configuration Provider System. For workbench-specific configuration discovery, see Workbench Structure and Discovery.

---

Configuration System Overview

The testbench configuration system aggregates settings from multiple sources to create a unified runtime environment. Configuration flows through three primary layers:

1. Primary Configuration (testbench.yaml): Defines providers, environment variables, workbench discovery settings, and cleanup rules
2. Application Configuration (workbench/config/*.php): Standard framework configuration files for application services
3. Environment Variables (.env): Generated from testbench.yaml and used at runtime via the env() helper

The configuration system operates during two distinct phases:

• Bootstrap Phase: One-time initialization when tests begin, loading testbench.yaml and generating environment files
• Application Creation Phase: Per-test instantiation where application configuration files are loaded and merged with environment variables

Sources: testbench.yaml1-20

---

Configuration Architecture

Diagram: Configuration Flow Architecture

This diagram illustrates how configuration data flows from source files through processing layers into the application container. The Bootstrapper handles one-time YAML parsing and .env generation, while TestCase::createApplication() loads application configuration files that merge with environment variables via the env() helper.

Sources: testbench.yaml1-20 workbench/config/app.php1-127

---

Configuration File Hierarchy

The testbench uses a hierarchical configuration structure with clear separation of concerns:

File/Directory	Purpose	Scope	Modification Frequency
testbench.yaml	Primary testbench configuration	Test environment setup	Per-project setup
workbench/config/app.php	Application-level settings	Application behavior	Per-project customization
workbench/config/database.php	Database connections	Database services	Environment-specific
workbench/config/session.php	Session management	Session driver configuration	Rarely modified
workbench/config/cors.php	CORS policies	HTTP security	Per-project requirements
workbench/config/auth.php	Authentication	Guards and providers	Per-authentication strategy
workbench/config/logging.php	Logging channels	Log output configuration	Per-environment needs
workbench/config/queue.php	Queue connections	Background job processing	Per-deployment
workbench/config/exceptions.php	Exception handling	Error reporting	Rarely modified
.env	Runtime environment variables	Generated from YAML	Auto-generated, ephemeral

Sources: testbench.yaml1-20 workbench/config/app.php1-127

---

testbench.yaml Structure

The testbench.yaml file serves as the primary configuration source for the testbench environment. It defines four main sections:

Providers Section

Specifies additional service providers to register during application bootstrapping. These providers supplement the default Hyperf and Hypervel providers managed by ConfigProviderRegister.

The WorkbenchServiceProvider is registered to enable workbench-specific features like route discovery and command registration.

Environment Variables Section

Defines environment variables that will be written to the generated .env file. These variables are accessible at runtime via the env() helper function.

Each entry uses the format KEY=value or KEY="value" for strings containing spaces.

Workbench Discovery Settings

Controls automatic discovery features for the workbench environment. When disabled, routes and commands must be manually registered.

Discovery Flag	Purpose	Default
web	Auto-register web routes from workbench/routes/web.php	false
api	Auto-register API routes from workbench/routes/api.php	false
commands	Auto-discover console commands in workbench/app/Console/Commands	false

Purge Configuration

Defines files and directories to clean up when the testbench environment is reset. This ensures a clean state between test runs.

The purge section specifies:

• files: Individual files to delete
• directories: Directories to recursively remove

Sources: testbench.yaml1-20

---

Application Configuration (app.php)

The workbench/config/app.php file defines core application settings. It follows Laravel's configuration conventions adapted for Hypervel/Hyperf.

Diagram: app.php Configuration Key Mapping

This diagram shows how configuration keys in app.php map to environment variables, with the env() helper providing default fallback values.

Core Application Settings

Configuration Key	Environment Variable	Default Value	Purpose
name	APP_NAME	'Hypervel'	Application name used in notifications and UI
env	APP_ENV	'dev'	Current environment (dev, production, testing)
debug	APP_DEBUG	true	Enable detailed error messages with stack traces
scan_cacheable	SCAN_CACHEABLE	false	Cache annotation scanning results for performance
url	APP_URL	'http://localhost'	Base URL for URL generation in console

The scan_cacheable setting controls whether Hyperf's annotation scanner caches results. This should be disabled during development to ensure code changes are detected.

Logging Configuration

The stdout_log_level array defines which PSR-3 log levels are written to standard output:

This configuration only affects the StdoutLogger provided by Hyperf. Other configured loggers (file, syslog, etc.) maintain their own level settings.

Internationalization Settings

Configuration Key	Environment Variable	Default Value	Purpose
timezone	APP_TIMEZONE	'UTC'	Default timezone for date/time functions
locale	APP_LOCALE	'en'	Default locale for translations
fallback_locale	APP_FALLBACK_LOCALE	'en'	Fallback locale when translation missing

Providers and Aliases

The providers and aliases keys load default framework providers and facade aliases:

These defaults are populated from:

• ServiceProvider::defaultProviders(): Returns the default collection of framework service providers
• Facade::defaultAliases(): Returns the default collection of facade class aliases

Additional providers can be registered via getPackageProviders() in test classes (see CreatesApplication Trait).

Sources: workbench/config/app.php1-127

---

Environment Variable Resolution

The env() helper function provides a consistent interface for accessing environment variables with fallback defaults. The resolution order is:

Diagram: env() Helper Resolution Order

The env() helper searches multiple sources in priority order, returning the first match or the provided default value if no match is found.

Type Casting

The env() helper automatically casts certain string values to appropriate PHP types:

String Value	Casted Type	Result
"true"	boolean	true
"false"	boolean	false
"null"	null	null
"empty"	string	"" (empty string)

Usage in Configuration Files

Configuration files should always use env() with sensible defaults:

The default value ensures the application functions correctly even if the environment variable is not set.

Sources: workbench/config/app.php21-48

---

Configuration Loading Sequence

Diagram: Configuration Loading Sequence

This sequence diagram shows the two-phase configuration loading process. The bootstrap phase occurs once per test run and handles YAML parsing and .env generation. The application phase occurs per test and loads configuration files with environment variable resolution.

Bootstrap Phase Details

During the one-time bootstrap phase (see Bootstrapper Lifecycle):

1. Bootstrapper::bootstrap() checks if initialization has already occurred via a static flag
2. testbench.yaml is parsed to extract providers, env, workbench, and purge sections
3. Environment variables from the env section are written to .env file
4. The BASE_PATH constant is defined to establish the workbench root directory
5. The ClassLoader is initialized with TestScanHandler for annotation scanning

Application Phase Details

During per-test application creation:

1. TestCase::createApplication() is called from setUp()
2. The .env file is loaded into the environment (via Dotenv or similar mechanism)
3. Configuration files from workbench/config/ are loaded in dependency order
4. Each env() call in configuration files resolves using the environment variable resolution order
5. The merged configuration is bound to the container as the config repository
6. Service providers access configuration via the config repository during registration

Sources: testbench.yaml1-20 workbench/config/app.php1-127

---

Configuration Override Patterns

Tests can override configuration through several mechanisms, listed in order of precedence (highest to lowest):

1. defineEnvironment Callback

The most flexible approach is overriding defineEnvironment() in test classes:

This method provides direct access to the config repository after initial loading but before providers are booted.

2. Environment Variables via putenv()

Set environment variables programmatically before application creation:

This affects env() calls during configuration loading.

3. Custom testbench.yaml

Create a project-specific testbench.yaml with custom settings:

This provides consistent configuration across all tests in the project.

4. Package Configuration

Package developers can provide default configuration via getPackageProviders() and custom service providers that publish configuration during boot.

Sources: workbench/config/app.php1-127

---

Configuration File Organization

Configuration files in workbench/config/ follow a standard organization pattern:

Configuration File	Primary Purpose	Key Services Configured
app.php	Application foundation	Application name, environment, timezone, locale
database.php	Database connections	Database drivers, Redis pools, connection parameters
session.php	Session management	Session driver, lifetime, cookies, encryption
cors.php	Cross-Origin Resource Sharing	CORS policies, allowed origins, methods, headers
auth.php	Authentication	Guards, providers, password reset settings
logging.php	Logging channels	Log drivers, paths, levels, formatting
queue.php	Queue connections	Queue drivers, connections, failed job handling
exceptions.php	Exception handling	Exception handler class, reporting configuration

Each configuration file returns an associative array that is merged into the application's config repository under a key matching the filename (e.g., app.php becomes accessible via config('app.key')).

For detailed documentation of specific configuration files, see:

• Application Configuration for app.php details
• Database Configuration for database.php details
• Session, CORS, and Security Configuration for session.php, cors.php, and auth.php details
• Logging, Queue, and Exception Configuration for logging.php, queue.php, and exceptions.php details

Sources: workbench/config/app.php1-127

---

Configuration Best Practices

Use Environment Variables for Environment-Specific Values

Configuration files should use env() for values that change between environments:

Always Provide Sensible Defaults

Every env() call should include a default value appropriate for the most common use case:

Avoid env() Calls Outside Configuration Files

The env() helper should only be used in configuration files. Application code should access configuration via the config repository:

This pattern allows configuration caching and provides a single source of truth.

Cache Configuration in Production

For production environments, consider caching configuration to improve performance. The Hyperf framework provides configuration caching mechanisms that serialize the entire config repository.

Sources: workbench/config/app.php1-127

---

Configuration Access Patterns

Accessing Configuration Values

The config repository provides several access patterns:

Setting Configuration Values at Runtime

Configuration can be modified at runtime via the config repository:

Runtime configuration changes affect the current request/test only and do not persist to configuration files.

Sources: workbench/config/app.php1-127